exampple v0.7.1 Exampple.Client

Client is a simple state machine inside of a process which helps us to create a client connection to a XMPP Server. The dynamic of the connection is contained inside of the client when we perform the connection and then we can send different kind of stanzas to the server.

The aim of this Client is to create a simple way to test the system but you can use it even to create bots based on XMPP.

It has the possibility to register templates and returns back the stanzas which are being received from the XMPP server to the calling process. This way we are responsible of the communication.

Templates

We have available the following templates:

  • init (domain): it sends the initial XML header. Requires the domain.
  • starttls: sends the stanza to init the TLS negotiation (WIP).
  • auth (user, password): send the auth stanza to the server.
  • bind (resource): establish the bind to a resource.
  • session: creates the session.
  • presence: sends a presence.
  • message (to, id, *kw_opts): build a message, it requires to specify different options. If we send body: "hello" then a body is created with that text as CDATA. We can also use payload: "<body>Hello</body>" to define the payload by ourselves. And even specify a type.
  • register (username, password): it sends the standard register stanza as is defined inside of the XEP-0077.

Checks

The checks are functions which check only the happy path, failing or raising an error if it's not finding what they need. We have defined the following checks:

  • auth: wait for the success stanza from the server.
  • init: wait for stream:features stanza and bind and session features inside.
  • bind: wait for the result IQ.
  • presence: wait for the available presence as an echo from the server.

Link to this section Summary

Functions

Adds a check to be in use by the process when we call check/2 or check/3. The name is the name or PID for the process, the key is the name we will use storing the template and fun is the function which will check the incoming stanza returning true or false if the check is passed.

Adds a template to be in use by the process when we call send_template/2 or send_template/3. The name is the name or PID for the process, the key is the name we will use storing the template and fun is the function which will generate the stanza.

Use a check registered inside of the client verifying if the incoming stanzas are passing the checks defined by the anonymous function. In the same way as the send_template/3 function it provides to the developer the ability to write better and shorter tests.

Returns a specification to start this module under a supervisor.

Send a message to the client process to start the connection. Optionally, we can specify the name of the process where to connect, by default this is the value provided by __MODULE__.

Send a message to the client process identified by name as PID or registered process to stop the connection. The name parameter is optional, by default it's set to __MODULE__.

Waits for an incoming connection / stanza which will be sent from the client process. It only works if we are using this function from the process which execute the start_link function or if we passed the PID of the current process as the name parameter. Optionally, we can configure a timeout, by default it's set to 5 seconds.

Same as get_conn/2 but we are waiting for a specific number of stanzas to be received indicated by num parameter. We have to indicate the name for the process where we are going to be connected.

Ask to the process about whether the connection is active. The checks are based on the process relanted to the passed name (it must be a registered name), the PID should be valid and alive, and then we ask to the client if it's connected. If no parameter is provided it is __MODULE__.

Send information (stanzas) via the client process directly to the XMPP Server. These stanzas could be sent to whoever inside of the XMPP network locally or even to other domains if the network is federated.

Use a template registered inside of the client. This let us to trigger faster stanzas when we are working from the shell. But also reduce the amount of code when we are developing tests.

Starts the client. We can send a name to be registered or use the module name (__MODULE__) by default. As args the system requires a Map with the information for the connection. The information we can provide is

Stops the process. You can specify the name of the process to be stopped, by default this value is set as __MODULE__.

Upgrade a connection as TLS.

Link to this section Functions

Link to this function

add_check(name \\ __MODULE__, key, fun)

add_check(atom(), atom(), (... -> boolean())) :: :ok

Adds a check to be in use by the process when we call check/2 or check/3. The name is the name or PID for the process, the key is the name we will use storing the template and fun is the function which will check the incoming stanza returning true or false if the check is passed.

Link to this function

add_template(name \\ __MODULE__, key, fun)

add_template(atom(), atom(), (... -> String.t())) :: :ok

Adds a template to be in use by the process when we call send_template/2 or send_template/3. The name is the name or PID for the process, the key is the name we will use storing the template and fun is the function which will generate the stanza.

Link to this function

callback_mode()

Link to this function

check!(template, args \\ [], name \\ __MODULE__)

check!(atom(), [any()], atom() | pid()) :: :ok

Use a check registered inside of the client verifying if the incoming stanzas are passing the checks defined by the anonymous function. In the same way as the send_template/3 function it provides to the developer the ability to write better and shorter tests.

We are providing the template name for the check, optionally some args if the check requires it and the name of the process for the client, by default it will be __MODULE__.

Link to this function

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor in Elixir v1.6+.

Link to this function

connect(name \\ __MODULE__)

connect(atom()) :: :ok

Send a message to the client process to start the connection. Optionally, we can specify the name of the process where to connect, by default this is the value provided by __MODULE__.

Link to this function

disconnect(name \\ __MODULE__)

Send a message to the client process identified by name as PID or registered process to stop the connection. The name parameter is optional, by default it's set to __MODULE__.

Link to this function

get_conn(name, timeout \\ 5000)

Waits for an incoming connection / stanza which will be sent from the client process. It only works if we are using this function from the process which execute the start_link function or if we passed the PID of the current process as the name parameter. Optionally, we can configure a timeout, by default it's set to 5 seconds.

Link to this function

get_conns(name, num, timeout \\ 5000)

Same as get_conn/2 but we are waiting for a specific number of stanzas to be received indicated by num parameter. We have to indicate the name for the process where we are going to be connected.

Optionally, we can configure a timeout, by default it's set to 5 seconds.

Link to this function

is_connected?(name \\ __MODULE__)

Ask to the process about whether the connection is active. The checks are based on the process relanted to the passed name (it must be a registered name), the PID should be valid and alive, and then we ask to the client if it's connected. If no parameter is provided it is __MODULE__.

Link to this function

send(data_or_conn, name \\ __MODULE__)

Send information (stanzas) via the client process directly to the XMPP Server. These stanzas could be sent to whoever inside of the XMPP network locally or even to other domains if the network is federated.

The accepted paramter data_or_conn could be a string (or binary) or a Conn struct. Optionally, you can specify a second parameter as the name of the registered process. The default value for the name paramter is __MODULE__.

Example:

iex> Exampple.Client.send("<presence/>")
:ok
Link to this function

send_template(template, args \\ [], name \\ __MODULE__)

send_template(atom(), [any()], atom() | pid()) :: :ok | :not_found

Use a template registered inside of the client. This let us to trigger faster stanzas when we are working from the shell. But also reduce the amount of code when we are developing tests.

The template parameter is an atom, the key for the keyword list of templates stored inside of the process. The args are the arguments passed to the function template. Finally the name is the name of the process where the request will be sent.

Link to this function

start_link(name \\ __MODULE__, args)

Starts the client. We can send a name to be registered or use the module name (__MODULE__) by default. As args the system requires a Map with the information for the connection. The information we can provide is:

  • host: the hostname or IP where we will be connected.
  • port: the port number where we will be connected.
  • domain: the XMPP domain we are going to use.
  • trimmed: if the stanzas will be trimmed (default false).
  • set_from: if we are going to set the from for each stanza written by the client (default false).
  • ping: if we active the ping. We can set here the number of milliseconds to send the ping or false to disable it (default false).
  • tcp_handler: the module which we will use to handle the connection (default Exampple.Tcp).
Link to this function

stop(name \\ __MODULE__)

Stops the process. You can specify the name of the process to be stopped, by default this value is set as __MODULE__.

Link to this function

upgrade_tls(name \\ __MODULE__)

upgrade_tls(atom()) :: :ok

Upgrade a connection as TLS.