Strophe: common.h File Reference

Strophe 0.13 XMPP client library

Data Structures | Macros | Typedefs | Enumerations | Functions
common.h File Reference

Internally used functions and structures. More...

## Data Structures
struct | xmpp_handlist_t
| handlers More...
struct | xmpp_connlist_t
struct | xmpp_ctx_t
struct | xmpp_send_queue_t
struct | xmpp_queue_t
struct | xmpp_sm_state_t
struct | conn_interface
struct | xmpp_conn_t
struct | xmpp_stanza_t

## Macros
#define | strophe_free_and_null(ctx, p)
#define | STR_MAYBE_NULL(p) (p)
#define | UNUSED(x) ((void)(x))
#define | MAX_DOMAIN_LEN 256
#define | SASL_MASK_PLAIN (1 << 0)
#define | SASL_MASK_DIGESTMD5 (1 << 1)
#define | SASL_MASK_ANONYMOUS (1 << 2)
#define | SASL_MASK_SCRAMSHA1 (1 << 3)
#define | SASL_MASK_SCRAMSHA256 (1 << 4)
#define | SASL_MASK_SCRAMSHA512 (1 << 5)
#define | SASL_MASK_EXTERNAL (1 << 6)
#define | SASL_MASK_SCRAMSHA1_PLUS (1 << 7)
#define | SASL_MASK_SCRAMSHA256_PLUS (1 << 8)
#define | SASL_MASK_SCRAM_PLUS (SASL_MASK_SCRAMSHA1_PLUS | SASL_MASK_SCRAMSHA256_PLUS)
#define | SASL_MASK_SCRAM_WEAK (SASL_MASK_SCRAMSHA1 | SASL_MASK_SCRAMSHA256 | SASL_MASK_SCRAMSHA512)
#define | SASL_MASK_SCRAM (SASL_MASK_SCRAM_PLUS | SASL_MASK_SCRAM_WEAK)

## Typedefs
typedef void(* | xmpp_open_handler) (xmpp_conn_t *conn)

## Enumerations
enum | xmpp_loop_status_t { XMPP_LOOP_NOTSTARTED , XMPP_LOOP_RUNNING , XMPP_LOOP_QUIT }
| run-time context More...
enum | xmpp_conn_state_t { XMPP_STATE_DISCONNECTED , XMPP_STATE_CONNECTING , XMPP_STATE_CONNECTED }
| connection More...
enum | xmpp_send_queue_owner_t { XMPP_QUEUE_STROPHE = 0x1 , XMPP_QUEUE_USER = 0x2 , XMPP_QUEUE_SM = 0x800 , XMPP_QUEUE_SM_STROPHE = XMPP_QUEUE_SM | XMPP_QUEUE_STROPHE }
enum | { XMPP_PORT_CLIENT = 5222 , XMPP_PORT_CLIENT_LEGACY_SSL = 5223 , XMPP_PORT_COMPONENT = 5347 }
enum | xmpp_stanza_type_t { XMPP_STANZA_UNKNOWN , XMPP_STANZA_TEXT , XMPP_STANZA_TAG }

## Functions
void * | strophe_alloc (const xmpp_ctx_t *ctx, size_t size)
| Allocate memory in a Strophe context.
void * | strophe_realloc (const xmpp_ctx_t *ctx, void *p, size_t size)
| Reallocate memory in a Strophe context.
char * | strophe_strdup (const xmpp_ctx_t *ctx, const char *s)
| implement our own strdup that uses the ctx allocator
char * | strophe_strndup (const xmpp_ctx_t *ctx, const char *s, size_t len)
| Duplicate a string with a maximum length.
void | strophe_free (const xmpp_ctx_t *ctx, void *p)
| Free memory in a Strophe context.
void | strophe_error (const xmpp_ctx_t *ctx, const char *area, const char *fmt,...)
| Write to the log at the ERROR level.
void | strophe_warn (const xmpp_ctx_t *ctx, const char *area, const char *fmt,...)
| Write to the log at the WARN level.
void | strophe_info (const xmpp_ctx_t *ctx, const char *area, const char *fmt,...)
| Write to the log at the INFO level.
void | strophe_debug (const xmpp_ctx_t *ctx, const char *area, const char *fmt,...)
| Write to the log at the DEBUG level.
void | strophe_debug_verbose (int level, const xmpp_ctx_t *ctx, const char *area, const char *fmt,...)
| Write to the log at the DEBUG level if verbosity is enabled.
void | strophe_log_internal (const xmpp_ctx_t *ctx, xmpp_log_level_t level, const char *area, const char *fmt, va_list ap)
int | conn_interface_write (struct conn_interface *intf, const void *buff, size_t len)
int | conn_int_nop (struct conn_interface *intf)
int | compression_init (xmpp_conn_t *conn)
void | compression_free (xmpp_conn_t *conn)
void | compression_handle_feature_children (xmpp_conn_t *conn, const char *text)
void | conn_disconnect (xmpp_conn_t *conn)
| Disconnect from the XMPP server.
void | conn_disconnect_clean (xmpp_conn_t *conn)
| Cleanly disconnect the connection.
void | conn_established (xmpp_conn_t *conn)
void | conn_open_stream (xmpp_conn_t *conn)
| Send the opening <stream:stream> tag to the server.
int | conn_tls_start (xmpp_conn_t *conn)
void | conn_prepare_reset (xmpp_conn_t *conn, xmpp_open_handler handler)
void | conn_parser_reset (xmpp_conn_t *conn)
void | handler_fire_stanza (xmpp_conn_t *conn, xmpp_stanza_t *stanza)
| Fire off all stanza handlers that match.
uint64_t | handler_fire_timed (xmpp_ctx_t *ctx)
| Fire off all timed handlers that are ready.
void | handler_reset_timed (xmpp_conn_t *conn, int user_only)
| Reset all timed handlers.
void | handler_add_timed (xmpp_conn_t *conn, xmpp_timed_handler handler, unsigned long period, void *userdata)
| Add a timed system handler.
void | handler_add_id (xmpp_conn_t *conn, xmpp_handler handler, const char *id, void *userdata)
| Add an id based system stanza handler.
void | handler_add (xmpp_conn_t *conn, xmpp_handler handler, const char *ns, const char *name, const char *type, void *userdata)
| Add a system stanza handler.
void | handler_system_delete_all (xmpp_conn_t *conn)
| Delete all system handlers.
void | reset_sm_state (xmpp_sm_state_t *sm_state)
void | disconnect_mem_error (xmpp_conn_t *conn)
| Disconnect the stream with a memory error.
void | auth_handle_open (xmpp_conn_t *conn)
| Set up handlers at stream start.
void | auth_handle_component_open (xmpp_conn_t *conn)
void | auth_handle_open_raw (xmpp_conn_t *conn)
void | auth_handle_open_stub (xmpp_conn_t *conn)
void | add_queue_back (xmpp_queue_t *queue, xmpp_send_queue_t *item)
xmpp_send_queue_t * | peek_queue_front (xmpp_queue_t *queue)
xmpp_send_queue_t * | pop_queue_front (xmpp_queue_t *queue)
char * | queue_element_free (xmpp_ctx_t *ctx, xmpp_send_queue_t *e)
void | send_raw (xmpp_conn_t *conn, const char *data, size_t len, xmpp_send_queue_owner_t owner, void *userdata)
void | send_raw_string (xmpp_conn_t *conn, const char *fmt,...)
void | send_stanza (xmpp_conn_t *conn, xmpp_stanza_t *stanza, xmpp_send_queue_owner_t owner)

## Detailed Description

Internally used functions and structures.

## Macro Definition Documentation

## ◆ strophe_free_and_null

#define strophe_free_and_null | ( |  | ctx,
|  |  | p )

Value:
do { \
if (p) { \
strophe_free(ctx, (p)); \
(p) = NULL; \
} \
} while (0)

## ◆ STR_MAYBE_NULL

#define STR_MAYBE_NULL | ( |  | p | ) | (p)

## ◆ UNUSED

#define UNUSED | ( |  | x | ) | ((void)(x))

## ◆ MAX_DOMAIN_LEN

#define MAX_DOMAIN_LEN 256

## ◆ SASL_MASK_PLAIN

#define SASL_MASK_PLAIN (1 << 0)

## ◆ SASL_MASK_DIGESTMD5

#define SASL_MASK_DIGESTMD5 (1 << 1)

## ◆ SASL_MASK_ANONYMOUS

#define SASL_MASK_ANONYMOUS (1 << 2)

## ◆ SASL_MASK_SCRAMSHA1

#define SASL_MASK_SCRAMSHA1 (1 << 3)

## ◆ SASL_MASK_SCRAMSHA256

#define SASL_MASK_SCRAMSHA256 (1 << 4)

## ◆ SASL_MASK_SCRAMSHA512

#define SASL_MASK_SCRAMSHA512 (1 << 5)

## ◆ SASL_MASK_EXTERNAL

#define SASL_MASK_EXTERNAL (1 << 6)

## ◆ SASL_MASK_SCRAMSHA1_PLUS

#define SASL_MASK_SCRAMSHA1_PLUS (1 << 7)

## ◆ SASL_MASK_SCRAMSHA256_PLUS

#define SASL_MASK_SCRAMSHA256_PLUS (1 << 8)

## ◆ SASL_MASK_SCRAM_PLUS

#define SASL_MASK_SCRAM_PLUS (SASL_MASK_SCRAMSHA1_PLUS | SASL_MASK_SCRAMSHA256_PLUS)

## ◆ SASL_MASK_SCRAM_WEAK

#define SASL_MASK_SCRAM_WEAK (SASL_MASK_SCRAMSHA1 | SASL_MASK_SCRAMSHA256 | SASL_MASK_SCRAMSHA512)

## ◆ SASL_MASK_SCRAM

#define SASL_MASK_SCRAM (SASL_MASK_SCRAM_PLUS | SASL_MASK_SCRAM_WEAK)

## Typedef Documentation

## ◆ xmpp_open_handler

typedef void(* xmpp_open_handler) (xmpp_conn_t *conn)

## Enumeration Type Documentation

## ◆ xmpp_loop_status_t

enum xmpp_loop_status_t

run-time context

Enumerator
XMPP_LOOP_NOTSTARTED |
XMPP_LOOP_RUNNING |
XMPP_LOOP_QUIT |

## ◆ xmpp_conn_state_t

enum xmpp_conn_state_t

connection

Enumerator
XMPP_STATE_DISCONNECTED |
XMPP_STATE_CONNECTING |
XMPP_STATE_CONNECTED |

## ◆ xmpp_send_queue_owner_t

enum xmpp_send_queue_owner_t

Enumerator
XMPP_QUEUE_STROPHE |
XMPP_QUEUE_USER |
XMPP_QUEUE_SM |
XMPP_QUEUE_SM_STROPHE |

## ◆ anonymous enum

anonymous enum

Enumerator
XMPP_PORT_CLIENT |
XMPP_PORT_CLIENT_LEGACY_SSL |
XMPP_PORT_COMPONENT |

## ◆ xmpp_stanza_type_t

enum xmpp_stanza_type_t

Enumerator
XMPP_STANZA_UNKNOWN |
XMPP_STANZA_TEXT |
XMPP_STANZA_TAG |

## Function Documentation

## ◆ strophe_alloc()

void * strophe_alloc | ( | const xmpp_ctx_t * | ctx,
|  | size_t | size )

Allocate memory in a Strophe context.

All Strophe functions will use this to allocate memory.

Parameters

  ctx | a Strophe context object
  size | the number of bytes to allocate

Returns
  a pointer to the allocated memory or NULL on an error

## ◆ strophe_realloc()

void * strophe_realloc | ( | const xmpp_ctx_t * | ctx,
|  | void * | p,
|  | size_t | size )

Reallocate memory in a Strophe context.

All Strophe functions will use this to reallocate memory.

Parameters

  ctx | a Strophe context object
  p | a pointer to previously allocated memory
  size | the new size in bytes to allocate

Returns
  a pointer to the reallocated memory or NULL on an error

## ◆ strophe_strdup()

char * strophe_strdup | ( | const xmpp_ctx_t * | ctx,
|  | const char * | s )

implement our own strdup that uses the ctx allocator

Duplicate a string. This function replaces the standard strdup library call with a version that uses the Strophe context object's allocator.

Parameters

  ctx | a Strophe context object
  s | a string

Returns
  a newly allocated string with the same data as s or NULL on error

## ◆ strophe_strndup()

char * strophe_strndup | ( | const xmpp_ctx_t * | ctx,
|  | const char * | s,
|  | size_t | len )

Duplicate a string with a maximum length.

This function replaces the standard strndup library call with a version that uses the Strophe context object's allocator.

Parameters

  ctx | a Strophe context object
  s | a string
  len | the maximum length of the string to copy

Returns
  a newly allocated string that contains at most `len` symbols of the original string or NULL on error

## ◆ strophe_free()

void strophe_free | ( | const xmpp_ctx_t * | ctx,
|  | void * | p )

Free memory in a Strophe context.

All Strophe functions will use this to free allocated memory.

Parameters

  ctx | a Strophe context object
  p | a pointer referencing memory to be freed

## ◆ strophe_error()

void strophe_error | ( | const xmpp_ctx_t * | ctx,
|  | const char * | area,
|  | const char * | fmt,
|  |  | ... )

Write to the log at the ERROR level.

This is a convenience function for writing to the log at the ERROR level. It takes a printf-style format string followed by a variable list of arguments for formatting.

Parameters

  ctx | a Strophe context object
  area | the area to log for
  fmt | a printf-style format string followed by a variable list of arguments to format

## ◆ strophe_warn()

void strophe_warn | ( | const xmpp_ctx_t * | ctx,
|  | const char * | area,
|  | const char * | fmt,
|  |  | ... )

Write to the log at the WARN level.

This is a convenience function for writing to the log at the WARN level. It takes a printf-style format string followed by a variable list of arguments for formatting.

Parameters

  ctx | a Strophe context object
  area | the area to log for
  fmt | a printf-style format string followed by a variable list of arguments to format

## ◆ strophe_info()

void strophe_info | ( | const xmpp_ctx_t * | ctx,
|  | const char * | area,
|  | const char * | fmt,
|  |  | ... )

Write to the log at the INFO level.

This is a convenience function for writing to the log at the INFO level. It takes a printf-style format string followed by a variable list of arguments for formatting.

Parameters

  ctx | a Strophe context object
  area | the area to log for
  fmt | a printf-style format string followed by a variable list of arguments to format

## ◆ strophe_debug()

void strophe_debug | ( | const xmpp_ctx_t * | ctx,
|  | const char * | area,
|  | const char * | fmt,
|  |  | ... )

Write to the log at the DEBUG level.

This is a convenience function for writing to the log at the DEBUG level. It takes a printf-style format string followed by a variable list of arguments for formatting.

Parameters

  ctx | a Strophe context object
  area | the area to log for
  fmt | a printf-style format string followed by a variable list of arguments to format

## ◆ strophe_debug_verbose()

void strophe_debug_verbose | ( | int | level,
|  | const xmpp_ctx_t * | ctx,
|  | const char * | area,
|  | const char * | fmt,
|  |  | ... )

Write to the log at the DEBUG level if verbosity is enabled.

This is a convenience function for writing to the log at the DEBUG level. It takes a printf-style format string followed by a variable list of arguments for formatting.

Parameters

  level | the verbosity level
  ctx | a Strophe context object
  area | the area to log for
  fmt | a printf-style format string followed by a variable list of arguments to format

## ◆ strophe_log_internal()

void strophe_log_internal | ( | const xmpp_ctx_t * | ctx,
|  | xmpp_log_level_t | level,
|  | const char * | area,
|  | const char * | fmt,
|  | va_list | ap )

## ◆ conn_interface_write()

int conn_interface_write | ( | struct conn_interface * | intf,
|  | const void * | buff,
|  | size_t | len )

## ◆ conn_int_nop()

int conn_int_nop | ( | struct conn_interface * | intf | ) |

## ◆ compression_init()

int compression_init | ( | xmpp_conn_t * | conn | ) |

## ◆ compression_free()

void compression_free | ( | xmpp_conn_t * | conn | ) |

## ◆ compression_handle_feature_children()

void compression_handle_feature_children | ( | xmpp_conn_t * | conn,
|  | const char * | text )

## ◆ conn_disconnect()

void conn_disconnect | ( | xmpp_conn_t * | conn | ) |

Disconnect from the XMPP server.

This function immediately disconnects from the XMPP server, and should not be used outside of the Strophe library.

Parameters

  conn | a Strophe connection object

## ◆ conn_disconnect_clean()

void conn_disconnect_clean | ( | xmpp_conn_t * | conn | ) |

Cleanly disconnect the connection.

This function is only called by the stream parser when </stream:stream> is received, and it not intended to be called by code outside of Strophe.

Parameters

  conn | a Strophe connection object

## ◆ conn_established()

void conn_established | ( | xmpp_conn_t * | conn | ) |

## ◆ conn_open_stream()

void conn_open_stream | ( | xmpp_conn_t * | conn | ) |

Send the opening <stream:stream> tag to the server.

This function is used by Strophe to begin an XMPP stream. It should not be used outside of the library.

Parameters

  conn | a Strophe connection object

## ◆ conn_tls_start()

int conn_tls_start | ( | xmpp_conn_t * | conn | ) |

## ◆ conn_prepare_reset()

void conn_prepare_reset | ( | xmpp_conn_t * | conn,
|  | xmpp_open_handler | handler )

## ◆ conn_parser_reset()

void conn_parser_reset | ( | xmpp_conn_t * | conn | ) |

## ◆ handler_fire_stanza()

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

Fire off all stanza handlers that match.

This function is called internally by the event loop whenever stanzas are received from the XMPP server.

Parameters

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

## ◆ handler_fire_timed()

uint64_t handler_fire_timed | ( | xmpp_ctx_t * | ctx | ) |

Fire off all timed handlers that are ready.

This function is called internally by the event loop.

Parameters

  ctx | a Strophe context object

Returns
  the time in milliseconds until the next handler will be ready

## ◆ handler_reset_timed()

void handler_reset_timed | ( | xmpp_conn_t * | conn,
|  | int | user_only )

Reset all timed handlers.

This function is called internally when a connection is successful.

Parameters

  conn | a Strophe connection object
  user_only | whether to reset all handlers or only user ones

## ◆ handler_add_timed()

void handler_add_timed | ( | xmpp_conn_t * | conn,
|  | xmpp_timed_handler | handler,
|  | unsigned long | period,
|  | void * | userdata )

Add a timed system handler.

This function is used to add internal timed handlers and should not be used outside of the library.

Parameters

  conn | a Strophe connection object
  handler | a function pointer to a timed handler
  period | the time in milliseconds between firings
  userdata | an opaque data pointer that will be passed to the handler

## ◆ handler_add_id()

void handler_add_id | ( | xmpp_conn_t * | conn,
|  | xmpp_handler | handler,
|  | const char * | id,
|  | void * | userdata )

Add an id based system stanza handler.

This function is used to add internal id based stanza handlers and should not be used outside of the library.

Parameters

  conn | a Strophe connection object
  handler | a function pointer to a stanza handler
  id | a string with the id
  userdata | an opaque data pointer that will be passed to the handler

## ◆ handler_add()

void handler_add | ( | xmpp_conn_t * | conn,
|  | xmpp_handler | handler,
|  | const char * | ns,
|  | const char * | name,
|  | const char * | type,
|  | void * | userdata )

Add a system stanza handler.

This function is used to add internal stanza handlers and should not be used outside of the library.

Parameters

  conn | a Strophe connection object
  handler | a function pointer to a stanza handler
  ns | a string with the namespace to match
  name | a string with the stanza name to match
  type | a string with the 'type' attribute value to match
  userdata | an opaque data pointer that will be passed to the handler

## ◆ handler_system_delete_all()

void handler_system_delete_all | ( | xmpp_conn_t * | conn | ) |

Delete all system handlers.

This function is used to reset conn object before re-connecting.

Parameters

  conn | a Strophe connection object

## ◆ reset_sm_state()

void reset_sm_state | ( | xmpp_sm_state_t * | sm_state | ) |

## ◆ disconnect_mem_error()

void disconnect_mem_error | ( | xmpp_conn_t * | conn | ) |

Disconnect the stream with a memory error.

This is a convenience function used internally by various parts of the Strophe library for terminating the connection because of a memory error.

Parameters

  conn | a Strophe connection object

## ◆ auth_handle_open()

void auth_handle_open | ( | xmpp_conn_t * | conn | ) |

Set up handlers at stream start.

This function is called internally to Strophe for handling the opening of an XMPP stream. It's called by the parser when a stream is opened or reset, and adds the initial handlers for <stream:error/> and <stream:features/>. This function is not intended for use outside of Strophe.

Parameters

  conn | a Strophe connection object

## ◆ auth_handle_component_open()

void auth_handle_component_open | ( | xmpp_conn_t * | conn | ) |

## ◆ auth_handle_open_raw()

void auth_handle_open_raw | ( | xmpp_conn_t * | conn | ) |

## ◆ auth_handle_open_stub()

void auth_handle_open_stub | ( | xmpp_conn_t * | conn | ) |

## ◆ add_queue_back()

void add_queue_back | ( | xmpp_queue_t * | queue,
|  | xmpp_send_queue_t * | item )

## ◆ peek_queue_front()

xmpp_send_queue_t * peek_queue_front | ( | xmpp_queue_t * | queue | ) |

## ◆ pop_queue_front()

xmpp_send_queue_t * pop_queue_front | ( | xmpp_queue_t * | queue | ) |

## ◆ queue_element_free()

char * queue_element_free | ( | xmpp_ctx_t * | ctx,
|  | xmpp_send_queue_t * | e )

## ◆ send_raw()

void send_raw | ( | xmpp_conn_t * | conn,
|  | const char * | data,
|  | size_t | len,
|  | xmpp_send_queue_owner_t | owner,
|  | void * | userdata )

## ◆ send_raw_string()

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

## ◆ send_stanza()

void send_stanza | ( | xmpp_conn_t * | conn,
|  | xmpp_stanza_t * | stanza,
|  | xmpp_send_queue_owner_t | owner )