Consumer API

Consumer API — Consumer library

Synopsis


#include <monitor/monp.h>


#define     MONP_CFG_GLOBAL
#define     MONP_CFG_USER
int         monp_lib_init                   (const char *config_file);
void        monp_lib_done                   (void);
int         monp_parse_url                  (const char *url,
                                             char **hostname,
                                             mon_addrlist *addr,
                                             monp_proto_module **proto);

#define     MONP_PROTOCOL_MODULE            (desc)
#define     MONP_SYMBOL_PROTOCOL
#define     MONP_PROTOCOL_API
            monp_proto_module;
            monp_proto_state;
int         monp_proto_register             (mon_module *module);
void        monp_proto_unregister           (mon_module *module);
monp_proto_module* monp_proto_get           (const char *proto);
void        monp_proto_done                 (monp_proto_module *proto);
void        monp_proto_ref                  (monp_proto_module *proto);

            monp_conn;
enum        monp_state;
enum        monp_flags;
monp_conn*  monp_conn_new                   (void);
void        monp_conn_done                  (monp_conn *conn);
int         monp_conn_connect               (monp_conn *conn,
                                             const char *url);
int         monp_conn_connect_full          (monp_conn *conn,
                                             const char *hostname,
                                             mon_addrlist *addr,
                                             monp_proto_module *proto);
int         monp_conn_connect_s             (monp_conn *conn,
                                             const char *url);
int         monp_conn_listen                (monp_conn *conn,
                                             mon_address *addr,
                                             monp_proto_module *proto);
monp_conn*  monp_conn_accept                (monp_conn *listener);
int         monp_conn_close                 (monp_conn *conn);
int         monp_conn_close_s               (monp_conn *conn);

monp_state  monp_conn_get_state             (monp_conn *conn);
int         monp_conn_get_sd                (monp_conn *conn);
int         monp_conn_get_caps              (monp_conn *conn,
                                             mon_msg_producer_caps **caps);
uint32_t    monp_conn_get_channel_id        (monp_conn *conn);
void*       monp_conn_get_aux               (monp_conn *conn);
void        monp_conn_set_aux               (monp_conn *conn,
                                             void *user_data,
                                             GDestroyNotify user_data_done);
void        monp_conn_set_metric_cb         (monp_conn *conn,
                                             monp_metric_cb cb);
void        monp_conn_set_cmd_cb            (monp_conn *conn,
                                             monp_cmd_cb cb);
monp_flags  monp_conn_get_flags             (monp_conn *conn);
int         monp_conn_set_flags             (monp_conn *conn,
                                             monp_flags flags);
int         monp_conn_clear_flags           (monp_conn *conn,
                                             monp_flags flags);
void        monp_conn_set_timeout           (monp_conn *conn,
                                             int timeout);
int         monp_conn_make_creds            (monp_conn *conn,
                                             const char *method,
                                             mon_auth_creds **creds,
                                             mon_cred_flags flags);
const char* monp_conn_get_server_name       (monp_conn *conn);

int         monp_send                       (monp_conn *conn);
int         monp_send_s                     (monp_conn *conn);

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

int         (*monp_metric_cb)               (monp_conn *conn,
                                             monp_metric_value *mv,
                                             void *user_data);
            monp_metric_value;
monp_metric_value* monp_metric_value_new    (struct timespec *tv,
                                             uint32_t metric_id);
void        monp_metric_value_free          (monp_metric_value *mv);
mon_metric_def* monp_metric_get_def         (monp_conn *conn,
                                             uint32_t metric_id);
void*       monp_metric_get_aux             (monp_conn *conn,
                                             uint32_t metric_id);
int         monp_metric_set_aux             (monp_conn *conn,
                                             uint32_t metric_id,
                                             void *user_data,
                                             GDestroyNotify user_data_done);
int         monp_metric_wait                (monp_conn *conn,
                                             uint32_t metric_id,
                                             monp_metric_value **mv);
mon_metric_def* monp_query_def              (monp_conn *conn,
                                             mon_metric_def_domain domain,
                                             const char *name);

int         (*monp_cmd_cb)                  (monp_conn *conn,
                                             mon_cmd cmd,
                                             mon_msg_cmd_response *cmd_resp,
                                             void *user_data);
int         monp_cmd_set_aux                (monp_conn *conn,
                                             uint32_t cmd_seq,
                                             void *user_data,
                                             GDestroyNotify user_data_done);

int         monp_cmd_collect                (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *name,
                                             mon_arg_list *args);
int         monp_cmd_stop                   (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t metric_id,
                                             uint32_t connection);
int         monp_cmd_get                    (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t metric_id,
                                             uint32_t connection);
int         monp_cmd_subscribe              (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t metric_id,
                                             uint32_t connection);
int         monp_cmd_buffer                 (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t metric_id,
                                             uint32_t connection);
int         monp_cmd_auth                   (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             mon_auth_creds *creds);
int         monp_cmd_query                  (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *name,
                                             mon_arg_list *args);
int         monp_cmd_def_channel            (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *url,
                                             mon_arg_list *args);
int         monp_cmd_set_channel            (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t channel_id);
int         monp_cmd_del_channel            (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             uint32_t channel_id);
int         monp_cmd_execute                (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *name,
                                             mon_arg_list *args);
int         monp_cmd_wrap                   (monp_conn *conn,
                                             uint32_t *cmd_seq,
                                             const char *layer);

int         monp_cmd_collect_s              (monp_conn *conn,
                                             const char *name,
                                             mon_arg_list *args,
                                             uint32_t *metric_id);
int         monp_cmd_stop_s                 (monp_conn *conn,
                                             uint32_t metric_id,
                                             uint32_t connection);
int         monp_cmd_get_s                  (monp_conn *conn,
                                             uint32_t metric_id,
                                             uint32_t connection);
int         monp_cmd_subscribe_s            (monp_conn *conn,
                                             uint32_t metric_id,
                                             uint32_t connection);
int         monp_cmd_buffer_s               (monp_conn *conn,
                                             uint32_t metric_id,
                                             uint32_t connection);
int         monp_cmd_auth_s                 (monp_conn *conn,
                                             mon_auth_creds *creds,
                                             uint32_t *channel_id);
int         monp_cmd_query_s                (monp_conn *conn,
                                             const char *name,
                                             mon_arg_list *args,
                                             uint32_t *metric_id);
int         monp_cmd_def_channel_s          (monp_conn *conn,
                                             const char *url,
                                             mon_arg_list *args,
                                             uint32_t *channel_id);
int         monp_cmd_set_channel_s          (monp_conn *conn,
                                             uint32_t channel_id);
int         monp_cmd_del_channel_s          (monp_conn *conn,
                                             uint32_t channel_id);
int         monp_cmd_execute_s              (monp_conn *conn,
                                             const char *name,
                                             mon_arg_list *args,
                                             uint32_t *metric_id);
int         monp_cmd_wrap_s                 (monp_conn *conn,
                                             const char *layer);

Description

There are two sets of functions for sending commands to the producer: synchronous and asynchronous.

Synchronous.  monp_cmd_collect_s(), monp_cmd_stop_s(), monp_cmd_subscribe_s(), monp_cmd_buffer_s(), monp_cmd_get_s(), monp_cmd_auth_s(), monp_cmd_def_channel_s(), monp_cmd_set_channel_s(), monp_cmd_del_channel_s(), monp_cmd_execute_s(), monp_cmd_query_s() and monp_cmd_wrap_s() send the respective command to the producer and wait for its completion. These functions are expected to operate on blocking-mode handles only; if the MONP_F_NONBLOCK flag is set on a connection handle, the result is undefined. Also, these functions may fail unexpectedly if there is no metric callback installed and an out-of-band metric value arrives before the completion of the command (this is allowed by the protocol). Therefore it is strongly recommended to always install a metric callback using monp_conn_set_metric_cb() if these functions are used. Synchronous operations may time out (and return MON_ERR_TIMEOUT) if a timeout was set by calling monp_conn_set_timeout(). This works only if the connection is in non-blocking mode (i.e. the MONP_F_NONBLOCK flag has been set) however; blocking read/write operations are not affected by the timeout. By default synchronous commands are interrupted when a signal is received. This behaviour can be disabled by setting the MONP_F_NOINTR flag for a connection. Note that after interrupting a synchronous command the state of the connection may become undefined, so the only reliable handling of such an event is destroying the connection.

Asynchronous.  monp_cmd_collect(), monp_cmd_stop(), monp_cmd_subscribe(), monp_cmd_buffer(), monp_cmd_get(), monp_cmd_auth(), monp_cmd_def_channel(), monp_cmd_set_channel(), monp_cmd_del_channel(), monp_cmd_execute(), monp_cmd_query() and monp_cmd_wrap() send the respective command to the producer without waiting for its completion. If the MONP_F_AUTOSEND flag is not set on the connection handle, the caller is expected to call monp_send() to actually send the command. Whenever data is ready on the network connection, monp_msg_parse() should be called to interpret the results.

Details

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.

config_file :name of configuration file to use.
Returns :0 on success or an error code.

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.

url :the URL to parse.
hostname :pointer to store the host name part of the URL. May be NULL if the caller is not interested in the host name. The returned string must be freed by the caller using g_free().
addr :a mon_addrlist to hold the network address(es).
proto :the monp_proto_module implementing the protocol binding.
Returns :0 if successful or an error code.

MONP_PROTOCOL_MODULE()

#define     MONP_PROTOCOL_MODULE(desc)

Declares a protocol module.

desc :the name of the protocol module descriptor.

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.

mon_module header;the generic loadable module header. The name field should be the name of the encoding.
int def_port;the default port used by this encoding.
init ()initialize internal protocol state.
destroy ()destroy the internal protocol state.
get_msg ()parse the next message from the producer.
cmd_collect ()encode a COLLECT command.
cmd_stop ()encode a STOP command.
cmd_subscribe ()encode a SUBSCRIBE command.
cmd_buffer ()encode a BUFFER command.
cmd_get ()encode a GET command.
cmd_auth ()encode an AUTH command.
cmd_def_channel ()encode a DEF_CHANNEL command.
cmd_set_channel ()encode a SET_CHANNEL command.
cmd_del_channel ()encode a DEL_CHANNEL command.
cmd_commit ()encode a COMMIT command.
cmd_execute ()encode an EXECUTE command.
cmd_query ()encode a QUERY command.
cmd_wrap ()encode a WRAP command.

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.

module :a monp_proto_module to register.
Returns :0 on success.

monp_proto_unregister ()

void        monp_proto_unregister           (mon_module *module);

Unregister a communication protocol module.

module :a monp_proto_module to unregister.

monp_proto_get ()

monp_proto_module* monp_proto_get           (const char *proto);

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

proto :the name of the protocol.
Returns :a monp_proto_module or NULL if the protocol name is not known.

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.

proto :a monp_proto_module.

monp_proto_ref ()

void        monp_proto_ref                  (monp_proto_module *proto);

Increase the reference count of a protocol module.

proto :a monp_proto_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.

MONP_STATE_UNINITIALIZEDthe connection handle is not initialized.
MONP_STATE_CONNECTINGconnect() is in progress.
MONP_STATE_OPENthe network connection has been established, but authentication has not been performed yet.
MONP_STATE_AUTHauthentication is in progress.
MONP_STATE_READYauthentication was successful, the connection is ready for sending commands.
MONP_STATE_WRAPa WRAP command is in progress. It is not allowed to issue any other commands until the WRAP completes.
MONP_STATE_CLOSINGclosing of the connection was requested.
MONP_STATE_CLOSEDthe network connection is closed.
MONP_STATE_ERRORa fatal error was encountered, the connection cannot be used anymore.

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_F_NONBLOCKnon-blocking I/O is used for communication on the connection. The effect of the synchronous command functions if this flag is set on a connection is undefined.
MONP_F_AUTOSENDautomatically flush the output buffer after every asynchronous command. If not set, the user must call monp_send() to actually send the command to the producer. It has no effect for the synchronous commands.
MONP_F_WANT_WRITEmonp_send() should be called when the network socket is ready for sending data.
MONP_F_WANT_READmonp_msg_parse() should be called when the network socket has data ready.
MONP_F_RETRY_READwe should do a read operation on the BIO stack before issuing other operations.
MONP_F_RETRY_WRITEwe should do a write operation on the BIO stack before issuing other operations.
MONP_F_NOINTRwhen this flag is set, synchronous commands cannot be interrupted by signals. If this flag is not set (the default), receiving a signal will cause the command to return with EAGAIN.

monp_conn_new ()

monp_conn*  monp_conn_new                   (void);

Allocates a new connection handle.

Returns :a monp_conn connection handle.

monp_conn_done ()

void        monp_conn_done                  (monp_conn *conn);

Close a connection and release all resources allocated to it.

conn :a monp_conn connection handle.

monp_conn_connect ()

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

Connect to the monitoring system at the specified url.

conn :a monp_conn connection handle. The handle must be in the MONP_STATE_UNINITIALIZED state.
url :an URL to connect to.
Returns :0 on success. MON_WANT_WRITE might be returned if the connection handle had been marked non-blocking and the connect() operation would block. Otherwise an error code is returned.

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.

conn :a monp_conn connection handle. The handle must be in the MONP_STATE_UNINITIALIZED state.
hostname :canonical host name to use for authentication and logging. If it is NULL, it will be deduced from addr.
addr :the list of addresses to try connecting to.
proto :the protocol encoding module to use on this connection.
Returns :0 if successful or an error code.

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.

conn :a monp_conn connection handle. The handle must be in the MONP_STATE_UNINITIALIZED state.
url :an URL to connect to.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
addr :the address to listen on.
proto :the protocol handler to use for incoming connections.
Returns :0 on success or an error code.

monp_conn_accept ()

monp_conn*  monp_conn_accept                (monp_conn *listener);

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

listener :a monp_conn listener handle.
Returns :a new handle for the incoming connection or NULL on error.

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.

conn :a monp_conn connection handle.
Returns :0 on success or an error code. MON_WANT_READ or MON_WANT_WRITE may be returned if the shutdown sequence requires communication with the peer.

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.

conn :a monp_conn connection handle.
Returns :0 on success or an error code.

monp_conn_get_state ()

monp_state  monp_conn_get_state             (monp_conn *conn);

Returns the current state of the connection.

conn :a monp_conn.
Returns :the connection's state.

monp_conn_get_sd ()

int         monp_conn_get_sd                (monp_conn *conn);

Returns the socket descriptor used by the connection.

conn :a monp_conn.
Returns :the socket descriptor.

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.

conn :a monp_conn.
caps :variable to hold the capabilities. Note: the returned pointer is only guaranteed to be valid until a synchronous command function or the monp_msg_parse() function is called.
Returns :0 if successful or an error code.

monp_conn_get_channel_id ()

uint32_t    monp_conn_get_channel_id        (monp_conn *conn);

Returns the channel id of the connection.

conn :a monp_conn.
Returns :the channel id of the connection. The result is valid only if authentication has been performed and was succesful.

monp_conn_get_aux ()

void*       monp_conn_get_aux               (monp_conn *conn);

Return the auxiliary data associated with this connection.

conn :a monp_conn.
Returns :

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.

conn :a monp_conn.
user_data :the auxiliary data.
user_data_done :a function to be called when the connection is destroyed. This function should deallocate resources used by the auxiliary data if neccessary.

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.

conn :a monp_conn.
cb :the metric callback function.

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.

conn :a monp_conn.
cb :the command completion callback function

monp_conn_get_flags ()

monp_flags  monp_conn_get_flags             (monp_conn *conn);

Get the connection's flags (see monp_flags).

conn :a monp_conn.
Returns :the connection's flags.

monp_conn_set_flags ()

int         monp_conn_set_flags             (monp_conn *conn,
                                             monp_flags flags);

Sets flags on the connection.

conn :a monp_conn.
flags :bitmask of the flags that should be set (see monp_flags).
Returns :0 if successful or an error code.

monp_conn_clear_flags ()

int         monp_conn_clear_flags           (monp_conn *conn,
                                             monp_flags flags);

Clears flags on the connection.

conn :a monp_conn.
flags :bitmask of the flags that should be cleared (see monp_flags).
Returns :0 if successful or an error code.

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.

conn :a monp_conn.
timeout :the timeout in milliseconds.

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.

conn :a monp_conn.
method :the authentication method to use.
creds :pointer to store the retrieved credentials if successful.
flags :credential flags.
Returns :0 if successful or an error code.

monp_conn_get_server_name ()

const char* monp_conn_get_server_name       (monp_conn *conn);

Returns the server name that is used for authentication.

conn :a monp_conn.
Returns :the name of the connected server.

monp_send ()

int         monp_send                       (monp_conn *conn);

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

conn :a monp_conn connection handle.
Returns :0 or an error code.

monp_send_s ()

int         monp_send_s                     (monp_conn *conn);

Send buffered data on a connection handle (blocking).

conn :a monp_conn connection handle.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
metric_id :returned metric ID.
msg :returned monp_msg structure.
Returns :0 on success, MON_CONTINUE if there is more data available or error code.

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).

conn :a monp_conn connection handle.
msg :a monp_msg structure.

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().

conn :a monp_conn connection handle.
mv :a metric value.
user_data :user-supplied pointer.
Returns :0 if the metric value was processed by this callback, MON_CONTINUE if it was not.

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.

uint32_t id;the numeric metric id.
struct timespec timestamp;the time of the measurement.
mon_buffer data;a mon_buffer containing the measured value.

monp_metric_value_new ()

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

Allocates a new metric value.

tv :timestamp of the metric value.
metric_id :identifier of the metric instance.
Returns :a new monp_metric_value or NULL on error.

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.

conn :a monp_conn.
metric_id :the metric id.
Returns :the metric definition or NULL if the metric id is invalid.

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.

conn :a monp_conn.
metric_id :the metric id.
Returns :

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.

conn :a monp_conn.
metric_id :the metric id.
user_data :the auxiliary data.
user_data_done :a function that will be called when the auxiliary data is no longer needed (the metric id is no longer valid). This function should deallocate resources used by the auxiliary data if neccessary.
Returns :0 if successful or an error code.

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.

conn :a monp_conn handle where a metric value arrived.
metric_id :a metric ID.
mv :returned monp_metric_value structure.
Returns :0 or an error code.

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.

conn :a monp_conn.
domain :either MON_DOM_METRIC or MON_DOM_CTRL.
name :the name of the metric or control.
Returns :a mon_metric_def or NULL if name is not known.

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().

conn :a monp_conn connection handle.
cmd :the command that has completed.
cmd_resp :the command response.
user_data :user-supplied data that was set by the monp_cmd_set_aux() function for this sequence number.
Returns :0 if the command response was processed by this callback, MON_CONTINUE if it was not.

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.

conn :a monp_conn connection handle.
cmd_seq :the command's sequence number.
user_data :the auxiliary data.
user_data_done :a function to be called when the connection is destroyed. This function should deallocate resources used by the auxiliary data if neccessary.
Returns :0 if successful or an error code.

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.

conn :a monp_conn handle where a command response arrived.
cmd_seq :a command ID.
name :name of the metric to collect.
args :a mon_arg_list with the metric arguments.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
metric_id :a metric ID.
connection :a connection ID to stop sending metric values to.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
metric_id :a metric ID.
connection :a channel ID.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
metric_id :a metric ID.
connection :a connection ID to send metric values to.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
metric_id :a metric ID.
connection :a connection ID to send metric values to.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
creds :a mon_auth_creds structure.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
name :name of the metric to query.
args :a mon_arg_list with the metric arguments.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
url :the URL the producer should connect to.
args :a mon_arg_list containing the properties of the new channel.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
channel_id :the channel ID to set.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
channel_id :the channel ID to delete.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
name :the name of the control to execute.
args :the arguments of the control.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
cmd_seq :a command ID.
layer :the I/O layer to use.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
name :name of the metric to collect.
args :a mon_arg_list with the metric arguments.
metric_id :returned ID for the metric instance.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
metric_id :a metric ID.
connection :a connection ID to stop sending metric values to.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
metric_id :a metric ID.
connection :a channel ID.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
metric_id :a metric ID.
connection :a connection ID to send metric values to.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
metric_id :a metric ID.
connection :a connection ID to send metric values to.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
creds :a mon_auth_creds structure.
channel_id :returned ID for the channel.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
name :name of the metric to query.
args :a mon_arg_list with the metric arguments.
metric_id :returned ID for the metric instance.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
url :the URL the producer should connect to.
args :a mon_arg_list containing the properties of the new channel.
channel_id :returned ID for the defined channel.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
channel_id :the channel ID to set.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
channel_id :the channel ID to delete.
Returns :0 or an error code.

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.

conn :a monp_conn connection handle.
name :the name of the control to execute.
args :the arguments of the control.
metric_id :contains the metric id of the control's result if the command is successful.
Returns :0 or an error code.

monp_cmd_wrap_s ()

int         monp_cmd_wrap_s                 (monp_conn *conn,
                                             const char *layer);
Send a WRAP command to the producer and wait for its completion.

conn :a monp_conn connection handle.
layer :the I/O layer to use.
Returns :0 or an error code.