Connection management

These functions manage a connection object. More...

## Typedefs

typedef int(* | xmpp_sockopt_callback) (xmpp_conn_t *conn, void *sock)
| The function which will be called when Strophe creates a new socket.
typedef void(* | xmpp_sm_callback) (xmpp_conn_t *conn, void *ctx, const unsigned char *sm_state, size_t sm_state_len)
| The function which will be called when Strophe updates its internal SM state.

## Functions

xmpp_conn_t * | xmpp_conn_new (xmpp_ctx_t *ctx)
| Create a new Strophe connection object.
xmpp_conn_t * | xmpp_conn_clone (xmpp_conn_t *conn)
| Clone a Strophe connection object.
void | xmpp_conn_set_sockopt_callback (xmpp_conn_t *conn, xmpp_sockopt_callback callback)
| Register sockopt callback Set function to be called when a new socket is created to allow setting socket options before connection is started.
int | xmpp_conn_release (xmpp_conn_t *conn)
| Release a Strophe connection object.
const char * | xmpp_conn_get_jid (const xmpp_conn_t *conn)
| Get the JID which is or will be bound to the connection.
const char * | xmpp_conn_get_bound_jid (const xmpp_conn_t *conn)
| Get the JID discovered during binding time.
void | xmpp_conn_set_jid (xmpp_conn_t *conn, const char *jid)
| Set the JID of the user that will be bound to the connection.
const char * | xmpp_conn_get_pass (const xmpp_conn_t *conn)
| Get the password used for authentication of a connection.
void | xmpp_conn_set_pass (xmpp_conn_t *conn, const char *pass)
| Set the password used to authenticate the connection.
xmpp_ctx_t * | xmpp_conn_get_context (xmpp_conn_t *conn)
| Get the strophe context that the connection is associated with.
int | xmpp_connect_client (xmpp_conn_t *conn, const char *altdomain, unsigned short altport, xmpp_conn_handler callback, void *userdata)
| Initiate a connection to the XMPP server.
int | xmpp_connect_component (xmpp_conn_t *conn, const char *server, unsigned short port, xmpp_conn_handler callback, void *userdata)
| Initiate a component connection to server.
int | xmpp_connect_raw (xmpp_conn_t *conn, const char *altdomain, unsigned short altport, xmpp_conn_handler callback, void *userdata)
| Initiate a raw connection to the XMPP server.
int | xmpp_conn_open_stream_default (xmpp_conn_t *conn)
| Send the default opening stream tag.
int | xmpp_conn_open_stream (xmpp_conn_t *conn, char **attributes, size_t attributes_len)
| Send an opening stream tag.
int | xmpp_conn_tls_start (xmpp_conn_t *conn)
| Start synchronous TLS handshake with the server.
void | xmpp_disconnect (xmpp_conn_t *conn)
| Initiate termination of the connection to the XMPP server.
void | xmpp_send_raw_string (xmpp_conn_t *conn, const char *fmt,...)
| Send a raw string to the XMPP server.
void | xmpp_send_raw (xmpp_conn_t *conn, const char *data, size_t len)
| Send raw bytes to the XMPP server.
void | xmpp_send (xmpp_conn_t *conn, xmpp_stanza_t *stanza)
| Send an XML stanza to the XMPP server.
long | xmpp_conn_get_flags (const xmpp_conn_t *conn)
| Return applied flags for the connection.
int | xmpp_conn_set_flags (xmpp_conn_t *conn, long flags)
| Set flags for the connection.
int | xmpp_conn_is_secured (xmpp_conn_t *conn)
| Return whether TLS session is established or not.
int | xmpp_conn_is_connecting (xmpp_conn_t *conn)
int | xmpp_conn_is_connected (xmpp_conn_t *conn)
int | xmpp_conn_is_disconnected (xmpp_conn_t *conn)
void | xmpp_conn_set_sm_callback (xmpp_conn_t *conn, xmpp_sm_callback cb, void *ctx)
| This sets the Stream Management callback function.
int | xmpp_conn_restore_sm_state (xmpp_conn_t *conn, const unsigned char *sm_state, size_t sm_state_len)
| This restores the serialized Stream Management state.
xmpp_sm_state_t * | xmpp_conn_get_sm_state (xmpp_conn_t *conn)
| This returns the Stream Management state of a connection object after it has been disconnected.
int | xmpp_conn_set_sm_state (xmpp_conn_t *conn, xmpp_sm_state_t *sm_state)
void | xmpp_free_sm_state (xmpp_sm_state_t *sm_state)
| c.f.
int | xmpp_conn_send_queue_len (const xmpp_conn_t *conn)
char * | xmpp_conn_send_queue_drop_element (xmpp_conn_t *conn, xmpp_queue_element_t which)
| Drop an element of the send queue.
int | xmpp_sockopt_cb_keepalive (xmpp_conn_t *conn, void *socket)
| Example sockopt callback function An example function that can be used to set reasonable default keepalive options on sockets when registered for a connection with xmpp_conn_set_sockopt_callback()

## Detailed Description

These functions manage a connection object.

A part of those functions is listed under the SSL/TLS specific functionality section.

## Typedef Documentation

## xmpp_sockopt_callback

typedef int(* xmpp_sockopt_callback) (xmpp_conn_t *conn, void *sock)

The function which will be called when Strophe creates a new socket.

The `sock` argument is a pointer that is dependent on the architecture Strophe is compiled for.

For POSIX compatible systems usage shall be:

int soc = *((int*)sock);

On Windows usage shall be:

SOCKET soc = *((SOCKET*)sock);

This function will be called for each socket that is created.

`examples/bot.c` uses a libstrophe supplied callback function that sets basic keepalive parameters (`xmpp_sockopt_cb_keepalive()`).

`examples/complex.c` implements a custom function that could be useful for an application.

Parameters

  conn | The Strophe connection object this callback originates from.
  sock | A pointer to the underlying file descriptor.

Returns
  0 on success, -1 on error

## xmpp_sm_callback

typedef void(* xmpp_sm_callback) (xmpp_conn_t *conn, void *ctx, const unsigned char *sm_state, size_t sm_state_len)

The function which will be called when Strophe updates its internal SM state.

Please note that you have to create a copy of the buffer, since the library will free the buffer right after return of the callback function.

Parameters

  conn | The Strophe connection object this callback originates from.
  ctx | The `ctx` pointer as passed to xmpp_conn_set_sm_callback
  sm_state | A pointer to a buffer containing the serialized SM state.
  sm_state_len | The length of `sm_state`.

Returns
  0 on success, -1 on error

## Function Documentation

## xmpp_conn_new()

xmpp_conn_t * xmpp_conn_new | ( | xmpp_ctx_t * | ctx | ) |

Create a new Strophe connection object.

Parameters

  ctx | a Strophe context object

Returns
  a Strophe connection object or NULL on an error

## xmpp_conn_clone()

xmpp_conn_t * xmpp_conn_clone | ( | xmpp_conn_t * | conn | ) |

Clone a Strophe connection object.

Parameters

  conn | a Strophe connection object

Returns
  the same conn object passed in with its reference count incremented by 1

## xmpp_conn_set_sockopt_callback()

void xmpp_conn_set_sockopt_callback | ( | xmpp_conn_t * | conn,
|  | xmpp_sockopt_callback | callback
| ) |  |

Register sockopt callback Set function to be called when a new socket is created to allow setting socket options before connection is started.

If the connection is already connected, this callback will be called immediately.

To set options that can only be applied to disconnected sockets, the callback must be registered before connecting.

Parameters

  conn | The Strophe connection object this callback is being registered for
  callback | a xmpp_sockopt_callback callback function that will receive notifications of connection status

## xmpp_conn_release()

int xmpp_conn_release | ( | xmpp_conn_t * | conn | ) |

Release a Strophe connection object.

Decrement the reference count by one for a connection, freeing the connection object if the count reaches 0.

Parameters

  conn | a Strophe connection object

Returns
  TRUE if the connection object was freed and FALSE otherwise

## xmpp_conn_get_jid()

const char * xmpp_conn_get_jid | ( | const xmpp_conn_t * | conn | ) |

Get the JID which is or will be bound to the connection.

Parameters

  conn | a Strophe connection object

Returns
  a string containing the full JID or NULL if it has not been set

## xmpp_conn_get_bound_jid()

const char * xmpp_conn_get_bound_jid | ( | const xmpp_conn_t * | conn | ) |

Get the JID discovered during binding time.

This JID will contain the resource used by the current connection. This is useful in the case where a resource was not specified for binding.

Parameters

  conn | a Strophe connection object.

Returns
  a string containing the full JID or NULL if it's not been discovered

## xmpp_conn_set_jid()

void xmpp_conn_set_jid | ( | xmpp_conn_t * | conn,
|  | const char * | jid
| ) |  |

Set the JID of the user that will be bound to the connection.

If any JID was previously set, it will be discarded. This should not be be used after a connection is created. The function will make a copy of the JID string. If the supplied JID is missing the node, SASL ANONYMOUS authentication will be used.

Parameters

  conn | a Strophe connection object
  jid | a full or bare JID

## xmpp_conn_get_pass()

const char * xmpp_conn_get_pass | ( | const xmpp_conn_t * | conn | ) |

Get the password used for authentication of a connection.

Parameters

  conn | a Strophe connection object

Returns
  a string containing the password or NULL if it has not been set

## xmpp_conn_set_pass()

void xmpp_conn_set_pass | ( | xmpp_conn_t * | conn,
|  | const char * | pass
| ) |  |

Set the password used to authenticate the connection.

If any password was previously set, it will be discarded. The function will make a copy of the password string.

Parameters

  conn | a Strophe connection object
  pass | the password

## xmpp_conn_get_context()

xmpp_ctx_t * xmpp_conn_get_context | ( | xmpp_conn_t * | conn | ) |

Get the strophe context that the connection is associated with.

Parameters

  conn | a Strophe connection object

Returns
  a Strophe context

## xmpp_connect_client()

int xmpp_connect_client | ( | xmpp_conn_t * | conn,
|  | const char * | altdomain,
|  | unsigned short | altport,
|  | xmpp_conn_handler | callback,
|  | void * | userdata
| ) |  |

Initiate a connection to the XMPP server.

This function returns immediately after starting the connection process to the XMPP server, and notifications of connection state changes will be sent to the callback function. The domain and port to connect to are usually determined by an SRV lookup for the xmpp-client service at the domain specified in the JID. If SRV lookup fails, altdomain and altport will be used instead if specified.

Parameters

  conn | a Strophe connection object
  altdomain | a string with domain to use if SRV lookup fails. If this is NULL, the domain from the JID will be used.
  altport | an integer port number to use if SRV lookup fails. If this is 0, the default port will be assumed.
  callback | a xmpp_conn_handler callback function that will receive notifications of connection status
  userdata | an opaque data pointer that will be passed to the callback

Returns
  XMPP_EOK (0) on success or a number less than 0 on failure

## xmpp_connect_component()

int xmpp_connect_component | ( | xmpp_conn_t * | conn,
|  | const char * | server,
|  | unsigned short | port,
|  | xmpp_conn_handler | callback,
|  | void * | userdata
| ) |  |

Initiate a component connection to server.

This function returns immediately after starting the connection process to the XMPP server, and notifications of connection state changes will be sent to the internal callback function that will set up handler for the component handshake as defined in XEP-0114. The domain and port to connect to must be provided in this case as the JID provided to the call serves as component identifier to the server and is not subject to DNS resolution.

Parameters

  conn | a Strophe connection object
  server | a string with domain to use directly as the domain can't be extracted from the component name/JID. If this is not set, the call will fail.
  port | an integer port number to use to connect to server expecting an external component. If this is 0, the port 5347 will be assumed.
  callback | a xmpp_conn_handler callback function that will receive notifications of connection status
  userdata | an opaque data pointer that will be passed to the callback

Returns
  XMPP_EOK (0) on success or a number less than 0 on failure

## xmpp_connect_raw()

int xmpp_connect_raw | ( | xmpp_conn_t * | conn,
|  | const char * | altdomain,
|  | unsigned short | altport,
|  | xmpp_conn_handler | callback,
|  | void * | userdata
| ) |  |

Initiate a raw connection to the XMPP server.

Arguments and behaviour of the function are similar to xmpp_connect_client(), but it skips authentication process. In opposite to xmpp_connect_client() during connection process two events are generated instead of one. User's callback is called with event XMPP_CONN_RAW_CONNECT when the TCP connection with the server is established. At this point user might want to open an XMPP stream with xmpp_conn_open_stream() or establish TLS session with xmpp_conn_tls_start(). Event XMPP_CONN_CONNECT is generated when the XMPP stream is opened successfully and user may send stanzas over the connection.

This function doesn't use password nor node part of a jid. Therefore, the only required configuration is a domain (or full jid) passed via xmpp_conn_set_jid().

See also
  xmpp_connect_client()

Returns
  XMPP_EOK (0) on success a number less than 0 on failure

## xmpp_conn_open_stream_default()

int xmpp_conn_open_stream_default | ( | xmpp_conn_t * | conn | ) |

Send the default opening stream tag.

The default tag is the one sent by xmpp_connect_client(). User's connection handler is called with event XMPP_CONN_CONNECT when server replies with its opening tag.

Returns
  XMPP_EOK (0) on success a number less than 0 on failure

Note
  The connection must be connected with xmpp_connect_raw().

## xmpp_conn_open_stream()

int xmpp_conn_open_stream | ( | xmpp_conn_t * | conn,
|  | char ** | attributes,
|  | size_t | attributes_len
| ) |  |

Send an opening stream tag.

User's connection handler is called with event XMPP_CONN_CONNECT when server replies with its opening tag.

Parameters

  conn | a Strophe connection object
  attributes | Array of strings in format: even index points to an attribute name and odd index points to its value
  attributes_len | Number of elements in the attributes array, it should be number of attributes multiplied by 2

Returns
  XMPP_EOK (0) on success a number less than 0 on failure

Note
  The connection must be connected with xmpp_connect_raw().

## xmpp_conn_tls_start()

int xmpp_conn_tls_start | ( | xmpp_conn_t * | conn | ) |

Start synchronous TLS handshake with the server.

Returns
  XMPP_EOK (0) on success a number less than 0 on failure

## xmpp_disconnect()

void xmpp_disconnect | ( | xmpp_conn_t * | conn | ) |

Initiate termination of the connection to the XMPP server.

This function starts the disconnection sequence by sending </stream:stream> to the XMPP server. This function will do nothing if the connection state is different from CONNECTING or CONNECTED.

Parameters

  conn | a Strophe connection object

## xmpp_send_raw_string()

void xmpp_send_raw_string | ( | xmpp_conn_t * | conn,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Send a raw string to the XMPP server.

This function is a convenience function to send raw string data to the XMPP server. It is used by Strophe to send short messages instead of building up an XML stanza with DOM methods. This should be used with care as it does not validate the data; invalid data may result in immediate stream termination by the XMPP server.

Parameters

  conn | a Strophe connection object
  fmt | a printf-style format string followed by a variable list of arguments to format

## xmpp_send_raw()

void xmpp_send_raw | ( | xmpp_conn_t * | conn,
|  | const char * | data,
|  | size_t | len
| ) |  |

Send raw bytes to the XMPP server.

This function is a convenience function to send raw bytes to the XMPP server. It is used primarily by xmpp_send_raw_string(). This function should be used with care as it does not validate the bytes and invalid data may result in stream termination by the XMPP server.

Parameters

  conn | a Strophe connection object
  data | a buffer of raw bytes
  len | the length of the data in the buffer

## xmpp_send()

void xmpp_send | ( | xmpp_conn_t * | conn,
|  | xmpp_stanza_t * | stanza
| ) |  |

Send an XML stanza to the XMPP server.

This is the main way to send data to the XMPP server. The function will terminate without action if the connection state is not CONNECTED.

Parameters

  conn | a Strophe connection object
  stanza | a Strophe stanza object

## xmpp_conn_get_flags()

long xmpp_conn_get_flags | ( | const xmpp_conn_t * | conn | ) |

Return applied flags for the connection.

Parameters

  conn | a Strophe connection object

Returns
  ORed connection flags that are applied for the connection.

## xmpp_conn_set_flags()

int xmpp_conn_set_flags | ( | xmpp_conn_t * | conn,
|  | long | flags
| ) |  |

Set flags for the connection.

This function applies set flags and resets unset ones. Default connection configuration is all flags unset. Flags can be applied only for a connection in disconnected state. All unsupported flags are ignored. If a flag is unset after successful set operation then the flag is not supported by current version.

Supported flags are:

- XMPP_CONN_FLAG_DISABLE_TLS
- XMPP_CONN_FLAG_MANDATORY_TLS
- XMPP_CONN_FLAG_LEGACY_SSL
- XMPP_CONN_FLAG_TRUST_TLS
- XMPP_CONN_FLAG_LEGACY_AUTH
- XMPP_CONN_FLAG_DISABLE_SM
- XMPP_CONN_FLAG_ENABLE_COMPRESSION
- XMPP_CONN_FLAG_COMPRESSION_DONT_RESET

Parameters

  conn | a Strophe connection object
  flags | ORed connection flags

Returns
  XMPP_EOK (0) on success or a number less than 0 on failure

## xmpp_conn_is_secured()

int xmpp_conn_is_secured | ( | xmpp_conn_t * | conn | ) |

Return whether TLS session is established or not.

Returns
  TRUE if TLS session is established and FALSE otherwise

## xmpp_conn_is_connecting()

int xmpp_conn_is_connecting | ( | xmpp_conn_t * | conn | ) |

Returns
  TRUE if connection is in connecting state and FALSE otherwise

## xmpp_conn_is_connected()

int xmpp_conn_is_connected | ( | xmpp_conn_t * | conn | ) |

Returns
  TRUE if connection is established and FALSE otherwise

## xmpp_conn_is_disconnected()

int xmpp_conn_is_disconnected | ( | xmpp_conn_t * | conn | ) |

Returns
  TRUE if connection is in disconnected state and FALSE otherwise

## xmpp_conn_set_sm_callback()

void xmpp_conn_set_sm_callback | ( | xmpp_conn_t * | conn,
|  | xmpp_sm_callback | cb,
|  | void * | ctx
| ) |  |

This sets the Stream Management callback function.

After setting this API, the library will call the given callback function each time when the internal SM state is updated.

This can be used in conjunction with xmpp_conn_restore_sm_state to e.g. implement a mechanism that retains an SM state over potential application terminations.

Parameters

  conn | a Strophe connection object
  cb | a callback function or NULL to disable
  ctx | a context that will be passed on invocation of the callback function

## xmpp_conn_restore_sm_state()

int xmpp_conn_restore_sm_state | ( | xmpp_conn_t * | conn,
|  | const unsigned char * | sm_state,
|  | size_t | sm_state_len
| ) |  |

This restores the serialized Stream Management state.

After setting this API, the library will call the given callback function each time when the internal SM state is updated.

This can be used in conjunction with xmpp_conn_restore_sm_state to e.g. implement a mechanism that retains an SM state over potential application terminations.

Parameters

  conn | a Strophe connection object
  sm_state | a buffer as passed to the SM callback
  sm_state_len | the length of `sm_state`

## xmpp_conn_get_sm_state()

xmpp_sm_state_t * xmpp_conn_get_sm_state | ( | xmpp_conn_t * | conn | ) |

This returns the Stream Management state of a connection object after it has been disconnected.

One can then initialise a fresh connection object and set this Stream Management state by calling xmpp_conn_set_sm_state

In case one wants to dispose of the state w/o setting it into a fresh connection object, one can call xmpp_free_sm_state

After calling this function to retrieve the state, only call one of the other two.

Parameters

  conn | a Strophe connection object

Returns
  The Stream Management state of the connection or NULL on error

## xmpp_conn_set_sm_state()

int xmpp_conn_set_sm_state | ( | xmpp_conn_t * | conn,
|  | xmpp_sm_state_t * | sm_state
| ) |  |

Parameters

  conn | a Strophe connection object
  sm_state | A Stream Management state returned from a call to `xmpp_conn_get_sm_state()`

Returns
  XMPP_EOK (0) on success or a number less than 0 on failure

## xmpp_free_sm_state()

void xmpp_free_sm_state | ( | xmpp_sm_state_t * | sm_state | ) |

c.f.

xmpp_conn_get_sm_state for usage documentation

Parameters

  sm_state | A Stream Management state returned from a call to `xmpp_conn_get_sm_state()`

## xmpp_conn_send_queue_len()

int xmpp_conn_send_queue_len | ( | const xmpp_conn_t * | conn | ) |

Returns
  The number of entries in the send queue

## xmpp_conn_send_queue_drop_element()

char * xmpp_conn_send_queue_drop_element | ( | xmpp_conn_t * | conn,
|  | xmpp_queue_element_t | which
| ) |  |

Drop an element of the send queue.

This can be used to manage the send queue in case a server isn't fast enough in processing the elements you're trying to send or your outgoing bandwidth isn't fast enough to transfer everything you want to send out.

Parameters

  conn | a Strophe connection object
  which | the element that shall be removed

Returns
  The rendered stanza. The pointer returned has to be free'd by the caller of this function.

## xmpp_sockopt_cb_keepalive()

int xmpp_sockopt_cb_keepalive | ( | xmpp_conn_t * | conn,
|  | void * | socket
| ) |  |

Example sockopt callback function An example function that can be used to set reasonable default keepalive options on sockets when registered for a connection with xmpp_conn_set_sockopt_callback()

Parameters

  conn | a Strophe connection object
  socket | pointer to a socket descriptor

See also
  xmpp_sockopt_callback for details on the `socket` parameter