Module amqp_connection

Description
Data Types
Function Index
Function Details

This module is responsible for maintaining a connection to an AMQP broker and manages channels within the connection.

Description

This module is responsible for maintaining a connection to an AMQP broker and manages channels within the connection. This module is used to open and close connections to the broker as well as creating new channels within a connection.
The connections and channels created by this module are supervised under amqp_client's supervision tree. Please note that connections and channels do not get restarted automatically by the supervision tree in the case of a failure. If you need robust connections and channels, we recommend you use Erlang monitors on the returned connection and channel PIDs.

In case of a failure or an AMQP error, the connection process exits with a meaningful exit reason:

Cause	Exit reason
Any reason, where Code would have been 200 otherwise	normal
User application calls amqp_connection:close/3	close_reason(app_initiated_close)
Server closes connection (hard error)	close_reason(server_initiated_close)
Server misbehaved (did not follow protocol)	close_reason(server_misbehaved)
AMQP client internal error - usually caused by a channel exiting with an unusual reason. This is usually accompanied by a more detailed error log from the channel	close_reason(internal_error)
Other error	(various error reasons, causing more detailed logging)

See type definitions below.

Data Types

amqp_adapter_info()

amqp_adapter_info() = #amqp_adapter_info{}

amqp_params_direct()

amqp_params_direct() = #amqp_params_direct{}

As defined in amqp_client.hrl. It contains the following fields:

username :: binary() - The name of a user registered with the broker, defaults to <<guest">>
password :: binary() - The password of user, defaults to 'none'
virtual_host :: binary() - The name of a virtual host in the broker, defaults to <<"/">>
node :: atom() - The node the broker runs on (direct only)
adapter_info :: amqp_adapter_info() - Extra management information for if this connection represents a non-AMQP network connection.
client_properties :: [{binary(), atom(), binary()}] | #{binary() => binary()} - A list (or a map) of extra client properties to be sent to the server, defaults to []

amqp_params_network()

amqp_params_network() = #amqp_params_network{}

As defined in amqp_client.hrl. It contains the following fields:

username :: binary() - The name of a user registered with the broker, defaults to <<guest">>
password :: binary() - The user's password, defaults to <<"guest">>
virtual_host :: binary() - The name of a virtual host in the broker, defaults to <<"/">>
host :: string() - The hostname of the broker, defaults to "localhost" (network only)
port :: integer() - The port the broker is listening on, defaults to 5672 (network only)
channel_max :: non_neg_integer() - The channel_max handshake parameter, defaults to 0
frame_max :: non_neg_integer() - The frame_max handshake parameter, defaults to 0 (network only)
heartbeat :: non_neg_integer() - The heartbeat interval in seconds, defaults to 0 (turned off) (network only)
connection_timeout :: non_neg_integer() | 'infinity' - The connection timeout in milliseconds, defaults to 30000 (network only)
ssl_options :: term() - The second parameter to be used with the ssl:connect/2 function, defaults to 'none' (network only)
client_properties :: [{binary(), atom(), binary()}] | #{binary() => binary()} - A list (or a map) of extra client properties to be sent to the server, defaults to []
socket_options :: [any()] - Extra socket options. These are appended to the default options. See inet:setopts/2 and gen_tcp:connect/4 for descriptions of the available options.

amqp_reason()

amqp_reason(Type) = {Type, Code, Text}

Code = non_neg_integer()
Text = binary()

close_reason()

close_reason(Type) = {shutdown, amqp_reason(Type)}

Function Index

close/1	Closes the channel, invokes close(Channel, 200, <<"Goodbye">>).
close/2	Closes the channel, using the supplied Timeout value.
close/3	Closes the AMQP connection, allowing the caller to set the reply code and text.
close/4	Closes the AMQP connection, allowing the caller to set the reply code and text, as well as a timeout for the operation, after which the connection will be abruptly terminated.
connection_name/1	Returns user specified connection name from client properties.
error_atom/1	Returns a descriptive atom corresponding to the given AMQP error code.
info/2	Returns information about the connection, as specified by the Items list.
info_keys/0	Returns a list of atoms that can be used in conjunction with info/2.
info_keys/1	Returns a list of atoms that can be used in conjunction with info/2.
open_channel/1	Invokes open_channel(ConnectionPid, none, {amqp_selective_consumer, []}).
open_channel/2	Invokes open_channel(ConnectionPid, none, Consumer).
open_channel/3	Opens an AMQP channel.
register_blocked_handler/2
socket_adapter_info/2	Takes a socket and a protocol, returns an #amqp_adapter_info{} based on the socket for the protocol given.
socket_adapter_info/3	Takes a socket and a protocol, returns an #amqp_adapter_info{} based on the socket for the protocol given.
start/1	same as start(Params, undefined)
start/2	Starts a connection to an AMQP server.
update_secret/3

Function Details

close/1

close(ConnectionPid) -> ok | Error

ConnectionPid = pid()

Closes the channel, invokes close(Channel, 200, <<"Goodbye">>).

close/2

close(ConnectionPid, Timeout) -> ok | Error

ConnectionPid = pid()
Timeout = integer()

Closes the channel, using the supplied Timeout value.

close/3

close(ConnectionPid, Code, Text) -> ok | closing

ConnectionPid = pid()
Code = integer()
Text = binary()

Closes the AMQP connection, allowing the caller to set the reply code and text.

close/4

close(ConnectionPid, Code, Text, Timeout) -> ok | closing

ConnectionPid = pid()
Code = integer()
Text = binary()
Timeout = integer()

Closes the AMQP connection, allowing the caller to set the reply code and text, as well as a timeout for the operation, after which the connection will be abruptly terminated.

connection_name/1

connection_name(ConnectionPid) -> ConnectionName

ConnectionPid = pid()
ConnectionName = binary()

Returns user specified connection name from client properties

error_atom/1

error_atom(Code) -> atom()

Code = integer()

Returns a descriptive atom corresponding to the given AMQP error code.

info/2

info(ConnectionPid, Items) -> ResultList

ConnectionPid = pid()
Items = [Item]
ResultList = [{Item, Result}]
Item = atom()
Result = term()

Returns information about the connection, as specified by the Items list. Item may be any atom returned by info_keys/1:

type - returns the type of the connection (network or direct)
server_properties - returns the server_properties fields sent by the server while establishing the connection
is_closing - returns true if the connection is in the process of closing and false otherwise
amqp_params - returns the #amqp_params{} structure used to start the connection
num_channels - returns the number of channels currently open under the connection (excluding channel 0)
channel_max - returns the channel_max value negotiated with the server
heartbeat - returns the heartbeat value negotiated with the server (only for the network connection)
frame_max - returns the frame_max value negotiated with the server (only for the network connection)
sock - returns the socket for the network connection (for use with e.g. inet:sockname/1) (only for the network connection)
any other value - throws an exception

info_keys/0

info_keys() -> Items

Items = [Item]
Item = atom()

Returns a list of atoms that can be used in conjunction with info/2. These are general info keys, which can be used in any type of connection. Other info keys may exist for a specific type. To get the full list of atoms that can be used for a certain connection, use info_keys/1.

info_keys/1

info_keys(ConnectionPid) -> Items

ConnectionPid = pid()
Items = [Item]
Item = atom()

Returns a list of atoms that can be used in conjunction with info/2. Note that the list differs from a type of connection to another (network vs. direct). Use info_keys/0 to get a list of info keys that can be used for any connection.

open_channel/1

open_channel(ConnectionPid) -> any()

Invokes open_channel(ConnectionPid, none, {amqp_selective_consumer, []}). Opens a channel without having to specify a channel number. This uses the default consumer implementation.

open_channel/2

open_channel(ConnectionPid, Consumer) -> any()

Invokes open_channel(ConnectionPid, none, Consumer). Opens a channel without having to specify a channel number.

open_channel/3

open_channel(ConnectionPid, ChannelNumber, Consumer) -> Result

ConnectionPid = pid()
ChannelNumber = pos_integer() | none
Consumer = {ConsumerModule, ConsumerArgs}
ConsumerModule = atom()
ConsumerArgs = [any()]
Result = {ok, ChannelPid} | {error, Error}
ChannelPid = pid()

Opens an AMQP channel.
Opens a channel, using a proposed channel number and a specific consumer implementation.
ConsumerModule must implement the amqp_gen_consumer behaviour. ConsumerArgs is passed as parameter to ConsumerModule:init/1.
This function assumes that an AMQP connection (networked or direct) has already been successfully established.
ChannelNumber must be less than or equal to the negotiated max_channel value, or less than or equal to ?MAX_CHANNEL_NUMBER (65535) if the negotiated max_channel value is 0.
In the direct connection, max_channel is always 0.

register_blocked_handler/2

register_blocked_handler(ConnectionPid, BlockHandler) -> any()

socket_adapter_info/2

socket_adapter_info(Sock, Protocol) -> any()

Takes a socket and a protocol, returns an #amqp_adapter_info{} based on the socket for the protocol given.

socket_adapter_info/3

socket_adapter_info(Sock, Protocol, UniqueId) -> any()

Takes a socket and a protocol, returns an #amqp_adapter_info{} based on the socket for the protocol given.

start/1

start(AmqpParams::Params) -> {ok, Connection} | {error, Error}

Params = amqp_params_network() | amqp_params_direct()
Connection = pid()

same as start(Params, undefined)

start/2

start(AmqpParams::Params, ConnName::ConnectionName) -> {ok, Connection} | {error, Error}

Params = amqp_params_network() | amqp_params_direct()
ConnectionName = undefined | binary()
Connection = pid()

Starts a connection to an AMQP server. Use network params to connect to a remote AMQP server or direct params for a direct connection to a RabbitMQ server, assuming that the server is running in the same process space. If the port is set to 'undefined', the default ports will be selected depending on whether this is a normal or an SSL connection. If ConnectionName is binary - it will be added to client_properties as user specified connection name.

update_secret/3

update_secret(ConnectionPid::pid(), NewSecret::term(), Reason::binary()) -> {ok, rabbit_types:auth_user()} | {refused, string(), [any()]} | {error, any()}

Generated by EDoc