MONP_CFG_GLOBAL

#define MONP_CFG_GLOBAL		"libmonp.conf"

The name of the global configuration file, relative to ${sysconfdir}.

MONP_CFG_USER

#define MONP_CFG_USER		".mercuryrc"

The name of the per-user configuration file, relative to the user's home dir.

monp_lib_init ()

int         monp_lib_init                   (const char *config_file);

Initialize the consumer library with the given configuration file.

monp_lib_done ()

void        monp_lib_done                   (void);

Shut down the consumer library and free any resources used internally.

monp_parse_url ()

int         monp_parse_url                  (const char *url,
                                             char **hostname,
                                             mon_addrlist *addr,
                                             monp_proto_module **proto);

Parse an URL string. The network address(es) will be appended to the addr list. The protocol module implementing the binding specified in the URL will be returned in proto.

MONP_PROTOCOL_MODULE()

#define     MONP_PROTOCOL_MODULE(desc)

Declares a protocol module.

MONP_SYMBOL_PROTOCOL

#define MONP_SYMBOL_PROTOCOL	MON_MODSYM(monp_module_protocol)

Defines the symbol name of the protocol module descriptor table in a loadable module.

MONP_PROTOCOL_API

#define MONP_PROTOCOL_API	3

Defines the protocol module API version used by the library.

monp_proto_module

typedef struct {
	/* Standard module header. The name field should contain the URI
	 * scheme */
	mon_module		header;

	/* Default port used by this protocol encoding */
	int			def_port;

	/* Internal protocol state handling */
	monp_proto_state	*(*init)(monp_conn *conn,
					mon_bio_head *bh);
	void			(*destroy)(monp_proto_state *proto);

	/* Decoding messages from the producer */
	int			(*get_msg)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t *metric_id,
					monp_msg *resp);

	/* Command encoding functions */
	int			(*cmd_collect)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					const char *name,
					const mon_arg_list *args);
	int			(*cmd_stop)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					uint32_t metric_id,
					uint32_t connection);
	int			(*cmd_subscribe)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					uint32_t metric_id,
					uint32_t connection);
	int			(*cmd_buffer)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					uint32_t metric_id,
					uint32_t connection);
	int			(*cmd_get)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					uint32_t metric_id,
					uint32_t connection);
	int			(*cmd_auth)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					const char *method,
					void *credentials,
					size_t credlen);
	int			(*cmd_def_channel)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					const char *url,
					const mon_arg_list *args);
	int			(*cmd_set_channel)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					uint32_t channel_id);
	int			(*cmd_del_channel)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					uint32_t channel_id);
	int			(*cmd_commit)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					uint64_t transaction);
	int			(*cmd_execute)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					const char *name,
					const mon_arg_list *args);
	int			(*cmd_query)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					const char *name,
					const mon_arg_list *args);
	int			(*cmd_wrap)(monp_proto_state *proto,
					mon_bio_head *bh,
					uint32_t cmd_seq,
					const char *layer);
} monp_proto_module;

This is the descriptor structure for a module implementing a protocol encoding.

monp_proto_state

typedef struct _monp_proto_state monp_proto_state;

Opaque structure representing the internal state of the protocol encoding module for this connection. The protocol encoding module may use it in any way it likes.

monp_proto_register ()

int         monp_proto_register             (mon_module *module);

Register a communication protocol module.

monp_proto_unregister ()

void        monp_proto_unregister           (mon_module *module);

Unregister a communication protocol module.

monp_proto_get ()

monp_proto_module* monp_proto_get           (const char *proto);

Look up a monp_proto_module based on the protocol's name.

monp_proto_done ()

void        monp_proto_done                 (monp_proto_module *proto);

Decrease the reference count of a protocol module. If the reference count goes to zero, the module is unloaded.

monp_proto_ref ()

void        monp_proto_ref                  (monp_proto_module *proto);

Increase the reference count of a protocol module.

monp_conn

typedef struct _monp_conn monp_conn;

The monp_conn opaque structure represents a connection handle to a producer.

enum monp_state

typedef enum {
	/* Connection is not initialized yet */
	MONP_STATE_UNINITIALIZED,
	/* connect() is in progress */
	MONP_STATE_CONNECTING,
	/* Connection open, capabilityes not received yet */
	MONP_STATE_OPEN,
	/* Authentication in progress */
	MONP_STATE_AUTH,
	/* The connection is ready for sending commands */
	MONP_STATE_READY,
	/* A WRAP command is pending */
	MONP_STATE_WRAP,
	/* The connection is being closed */
	MONP_STATE_CLOSING,
	/* The connection is closed */
	MONP_STATE_CLOSED,
	/* The connection has an error condition */
	MONP_STATE_ERROR
} monp_state;

The state of a monp_conn.

enum monp_flags

typedef enum {
	MONP_F_NONBLOCK			= (1 << 0),
	MONP_F_AUTOSEND			= (1 << 1),
	MONP_F_WANT_WRITE		= (1 << 2),
	MONP_F_WANT_READ		= (1 << 3),
	MONP_F_RETRY_READ		= (1 << 4),
	MONP_F_RETRY_WRITE		= (1 << 5),
	MONP_F_NOINTR			= (1 << 6)
} monp_flags;

Flags for a monp_conn.

monp_conn_new ()

monp_conn*  monp_conn_new                   (void);

Allocates a new connection handle.

monp_conn_done ()

void        monp_conn_done                  (monp_conn *conn);

Close a connection and release all resources allocated to it.

monp_conn_connect ()

int         monp_conn_connect               (monp_conn *conn,
                                             const char *url);

Connect to the monitoring system at the specified url.

monp_conn_connect_full ()

int         monp_conn_connect_full          (monp_conn *conn,
                                             const char *hostname,
                                             mon_addrlist *addr,
                                             monp_proto_module *proto);

Connect to the monitoring system at the specified address using the given protocol module.

monp_conn_connect_s ()

int         monp_conn_connect_s             (monp_conn *conn,
                                             const char *url);

Connect to the monitoring system at the specified url. This version is synchronous, it waits till the network connection is established.

monp_conn_listen ()

int         monp_conn_listen                (monp_conn *conn,
                                             mon_address *addr,
                                             monp_proto_module *proto);

Listen on the interface/port specified by addr.

monp_conn_accept ()

monp_conn*  monp_conn_accept                (monp_conn *listener);

Accept an incoming connection on a listener handle created by monp_conn_listen().

monp_conn_close ()

int         monp_conn_close                 (monp_conn *conn);

Close the network connection of the monp_conn handle. This shuts down all I/O layers properly.

monp_conn_close_s ()

int         monp_conn_close_s               (monp_conn *conn);

Close the network connection of the monp_conn handle. If an I/O layer requires communication with the peer for the shutdown sequence, this function will block until all such communication are finished.

monp_conn_get_state ()

monp_state  monp_conn_get_state             (monp_conn *conn);

Returns the current state of the connection.

monp_conn_get_sd ()

int         monp_conn_get_sd                (monp_conn *conn);

Returns the socket descriptor used by the connection.

monp_conn_get_caps ()

int         monp_conn_get_caps              (monp_conn *conn,
                                             mon_msg_producer_caps **caps);

Retrieve the producer capabilities. If the capabilities has not arrived yet and the MONP_F_NONBLOCK flag is not set on the connection, thsi function blocks until the capabilities are received.

monp_conn_get_channel_id ()

uint32_t    monp_conn_get_channel_id        (monp_conn *conn);

Returns the channel id of the connection.

monp_conn_get_aux ()

void*       monp_conn_get_aux               (monp_conn *conn);

Return the auxiliary data associated with this connection.

monp_conn_set_aux ()

void        monp_conn_set_aux               (monp_conn *conn,
                                             void *user_data,
                                             GDestroyNotify user_data_done);

Set the auxiliary data for this connection.

monp_conn_set_metric_cb ()

void        monp_conn_set_metric_cb         (monp_conn *conn,
                                             monp_metric_cb cb);

Set the metric callback function for this connection. This function will be called whenever a new metric value arrives.

monp_conn_set_cmd_cb ()

void        monp_conn_set_cmd_cb            (monp_conn *conn,
                                             monp_cmd_cb cb);

Set the command completion callback function for this connection. This function will be called whenever the result of a previously issued command arrives.

monp_conn_get_flags ()

monp_flags  monp_conn_get_flags             (monp_conn *conn);

Get the connection's flags (see monp_flags).

monp_conn_set_flags ()

int         monp_conn_set_flags             (monp_conn *conn,
                                             monp_flags flags);

Sets flags on the connection.

monp_conn_clear_flags ()

int         monp_conn_clear_flags           (monp_conn *conn,
                                             monp_flags flags);

Clears flags on the connection.

monp_conn_set_timeout ()

void        monp_conn_set_timeout           (monp_conn *conn,
                                             int timeout);

Sets the timeout for synchronous operations. The timeout is honoured only if the connection is in non-blocking mode.

monp_conn_make_creds ()

int         monp_conn_make_creds            (monp_conn *conn,
                                             const char *method,
                                             mon_auth_creds **creds,
                                             mon_cred_flags flags);

Retrieves the credentials for the method authentication method.

monp_conn_get_server_name ()

const char* monp_conn_get_server_name       (monp_conn *conn);

Returns the server name that is used for authentication.

monp_send ()

int         monp_send                       (monp_conn *conn);

Send buffered data on a connection handle like monp_send_s() but honour non-blocking mode.

monp_send_s ()

int         monp_send_s                     (monp_conn *conn);

Send buffered data on a connection handle (blocking).

monp_msg

typedef struct {
	mon_format			format;
	union
	{
		mon_msg_cmd_response	resp;
		monp_metric_value	*mv;
		mon_msg_producer_caps	caps;
		mon_msg_data		data;
	};
} monp_msg;

The monp_msg structure encapsulates every possible data that can arrive from the producer: command responses, metric values and producer capabilities.

monp_msg_parse ()

int         monp_msg_parse                  (monp_conn *conn,
                                             uint32_t *metric_id,
                                             monp_msg *msg);

Try to read and parse data from the producer. If metric and/or command callbacks are registered, they will be called to handle the returned data and this function will always return MON_CONTINUE. If one or both of the callbacks are not registered, the data will be returned directly in metric_id and msg.

monp_msg_destroy ()

void        monp_msg_destroy                (monp_conn *conn,
                                             monp_msg *msg);

Destroy the memory allocated to a monp_msg structure (does not free the structure itself).

monp_metric_cb ()

int         (*monp_metric_cb)               (monp_conn *conn,
                                             monp_metric_value *mv,
                                             void *user_data);

Specifies the type of the function which is passed to monp_conn_set_metric_cb().

monp_metric_value

typedef struct {
	uint32_t		id;
	struct timespec		timestamp;
	mon_buffer		data;
} monp_metric_value;

The monp_metric_value struct represents a metric value.

monp_metric_value_new ()

monp_metric_value* monp_metric_value_new    (struct timespec *tv,
                                             uint32_t metric_id);

Allocates a new metric value.

monp_metric_value_free ()

void        monp_metric_value_free          (monp_metric_value *mv);

Free the memory allocated to a metric value.

monp_metric_get_def ()

mon_metric_def* monp_metric_get_def         (monp_conn *conn,
                                             uint32_t metric_id);

Returns the metric definition for a metric id. The reference count of the metric definition is incremented so the caller should call mon_metric_def_done() when the definition is no longer needed.

monp_metric_get_aux ()

void*       monp_metric_get_aux             (monp_conn *conn,
                                             uint32_t metric_id);

Retrieves the auxiliary data associated with a metric id.

monp_metric_set_aux ()

int         monp_metric_set_aux             (monp_conn *conn,
                                             uint32_t metric_id,
                                             void *user_data,
                                             GDestroyNotify user_data_done);

Set auxiliary data associated with a metric id.

monp_metric_wait ()

int         monp_metric_wait                (monp_conn *conn,
                                             uint32_t metric_id,
                                             monp_metric_value **mv);

Wait until a value for the metric identified by metric_id arrives and return it in mv.

monp_query_def ()

mon_metric_def* monp_query_def              (monp_conn *conn,
                                             mon_metric_def_domain domain,
                                             const char *name);

Queries the definition of a metric or control from the producer.

monp_cmd_cb ()

int         (*monp_cmd_cb)                  (monp_conn *conn,
                                             mon_cmd cmd,
                                             mon_msg_cmd_response *cmd_resp,
                                             void *user_data);

Specifies the type of the function which is passed to monp_conn_set_cmd_cb().

monp_cmd_set_aux ()

int         monp_cmd_set_aux                (monp_conn *conn,
                                             uint32_t cmd_seq,
                                             void *user_data,
                                             GDestroyNotify user_data_done);

Sets the auxiliary data for a command.

monp_cmd_collect ()

int         monp_cmd_collect                (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *name,
                                             mon_arg_list *args);

Sends a COLLECT command to the producer without waiting for completion.

monp_cmd_stop ()

int         monp_cmd_stop                   (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t metric_id,
                                             uint32_t connection);

Send a STOP command to the producer without waiting for completion.

monp_cmd_get ()

int         monp_cmd_get                    (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t metric_id,
                                             uint32_t connection);

Send a GET command to the producer without waiting for completion.

monp_cmd_subscribe ()

int         monp_cmd_subscribe              (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t metric_id,
                                             uint32_t connection);

Send a SUBSCRIBE command to the producer without waiting for completion.

monp_cmd_buffer ()

int         monp_cmd_buffer                 (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t metric_id,
                                             uint32_t connection);

Send a BUFFER command to the producer without waiting for completion.

monp_cmd_auth ()

int         monp_cmd_auth                   (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             mon_auth_creds *creds);

Send an AUTH command to the producer without waiting for completion. Multi-step authentication is handled transparently by the library. This means that only the final result will be reported to the command callback.

monp_cmd_query ()

int         monp_cmd_query                  (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *name,
                                             mon_arg_list *args);

Send a QUERY command to the producer without waiting for completion.

monp_cmd_def_channel ()

int         monp_cmd_def_channel            (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *url,
                                             mon_arg_list *args);

Send a DEF_CHANNEL command to the producer without waiting for completion.

monp_cmd_set_channel ()

int         monp_cmd_set_channel            (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t channel_id);

Send a SET_CHANNEL command to the producer without waiting for competion.

monp_cmd_del_channel ()

int         monp_cmd_del_channel            (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t channel_id);

Send a DEL_CHANNEL command to the producer without waiting for competion.

monp_cmd_execute ()

int         monp_cmd_execute                (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *name,
                                             mon_arg_list *args);

Send a EXECUTE command to the producer without waiting for competion.

monp_cmd_wrap ()

int         monp_cmd_wrap                   (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *layer);

Send a WRAP command to the producer without waiting for competion.

monp_cmd_collect_s ()

int         monp_cmd_collect_s              (monp_conn *conn,
                                             const char *name,
                                             mon_arg_list *args,
                                             uint32_t *metric_id);

Send a COLLECT command to the producer and wait for its completion.

monp_cmd_stop_s ()

int         monp_cmd_stop_s                 (monp_conn *conn,
                                             uint32_t metric_id,
                                             uint32_t connection);

Send a STOP command to the producer and wait for its completion.

monp_cmd_get_s ()

int         monp_cmd_get_s                  (monp_conn *conn,
                                             uint32_t metric_id,
                                             uint32_t connection);

Send a GET command to the producer and wait for its completion.

monp_cmd_subscribe_s ()

int         monp_cmd_subscribe_s            (monp_conn *conn,
                                             uint32_t metric_id,
                                             uint32_t connection);

Send a SUBSCRIBE command to the producer and wait for its completion.

monp_cmd_buffer_s ()

int         monp_cmd_buffer_s               (monp_conn *conn,
                                             uint32_t metric_id,
                                             uint32_t connection);

Send a BUFFER command to the producer and wait for its completion.

monp_cmd_auth_s ()

int         monp_cmd_auth_s                 (monp_conn *conn,
                                             mon_auth_creds *creds,
                                             uint32_t *channel_id);

Send an AUTH command to the producer and wait for its completion.

monp_cmd_query_s ()

int         monp_cmd_query_s                (monp_conn *conn,
                                             const char *name,
                                             mon_arg_list *args,
                                             uint32_t *metric_id);

Send a QUERY command to the producer and wait for its completion.

monp_cmd_def_channel_s ()

int         monp_cmd_def_channel_s          (monp_conn *conn,
                                             const char *url,
                                             mon_arg_list *args,
                                             uint32_t *channel_id);

Send a DEF_CHANNEL command to the producer and wait for its completion.

monp_cmd_set_channel_s ()

int         monp_cmd_set_channel_s          (monp_conn *conn,
                                             uint32_t channel_id);

Send a SET_CHANNEL command to the producer and wait for its completion.

monp_cmd_del_channel_s ()

int         monp_cmd_del_channel_s          (monp_conn *conn,
                                             uint32_t channel_id);

Send a DEL_CHANNEL command to the producer and wait for its completion.

monp_cmd_execute_s ()

int         monp_cmd_execute_s              (monp_conn *conn,
                                             const char *name,
                                             mon_arg_list *args,
                                             uint32_t *metric_id);

Send a EXECUTE command to the producer and wait for its completion.

monp_cmd_wrap_s ()

int         monp_cmd_wrap_s                 (monp_conn *conn,
                                             const char *layer);