libprelude Reference Manual | ||||
---|---|---|---|---|
Top | Description |
enum prelude_connection_pool_flags_t; enum prelude_connection_pool_event_t; typedef prelude_connection_pool_t; void prelude_connection_pool_broadcast (prelude_connection_pool_t *pool, prelude_msg_t *msg); void prelude_connection_pool_broadcast_async (prelude_connection_pool_t *pool, prelude_msg_t *msg); int prelude_connection_pool_init (prelude_connection_pool_t *pool); int prelude_connection_pool_new (prelude_connection_pool_t **ret, prelude_client_profile_t *cp, prelude_connection_permission_t permission); prelude_connection_pool_t * prelude_connection_pool_ref (prelude_connection_pool_t *pool); prelude_list_t * prelude_connection_pool_get_connection_list (prelude_connection_pool_t *pool); int prelude_connection_pool_add_connection (prelude_connection_pool_t *pool, prelude_connection_t *cnx); int prelude_connection_pool_del_connection (prelude_connection_pool_t *pool, prelude_connection_t *cnx); int prelude_connection_pool_set_connection_dead (prelude_connection_pool_t *pool, prelude_connection_t *cnx); int prelude_connection_pool_set_connection_alive (prelude_connection_pool_t *pool, prelude_connection_t *cnx); int prelude_connection_pool_set_connection_string (prelude_connection_pool_t *pool, const char *cfgstr); const char * prelude_connection_pool_get_connection_string (prelude_connection_pool_t *pool); void prelude_connection_pool_destroy (prelude_connection_pool_t *pool); prelude_connection_pool_flags_t prelude_connection_pool_get_flags (prelude_connection_pool_t *pool); void prelude_connection_pool_set_flags (prelude_connection_pool_t *pool, prelude_connection_pool_flags_t flags); void prelude_connection_pool_set_required_permission (prelude_connection_pool_t *pool, prelude_connection_permission_t req_perm); void prelude_connection_pool_set_data (prelude_connection_pool_t *pool, void *data); void * prelude_connection_pool_get_data (prelude_connection_pool_t *pool); int prelude_connection_pool_recv (prelude_connection_pool_t *pool, int timeout, prelude_connection_t **outcon, prelude_msg_t **outmsg); int prelude_connection_pool_check_event (prelude_connection_pool_t *pool, int timeout, int (event_cbprelude_connection_pool_t *pool,prelude_connection_pool_event_t event,prelude_connection_t *cnx, void *extra) (), void *extra); void prelude_connection_pool_set_global_event_handler (prelude_connection_pool_t *pool, prelude_connection_pool_event_t wanted_events, int (callbackprelude_connection_pool_t *pool,prelude_connection_pool_event_t events) ()); void prelude_connection_pool_set_event_handler (prelude_connection_pool_t *pool, prelude_connection_pool_event_t wanted_events, int (callbackprelude_connection_pool_t *pool,prelude_connection_pool_event_t events,prelude_connection_t *cnx) ());
This API handle pool of connection, allowing to address a set of connection using only one object.
AND & OR of connection are supported, so that it is possible to address several connection at once, or to only address a set of connection if another connection went down.
Additionally it provide failover in case one of the connection in the pool goes down, and automatic reconnection and flushing of the information that could not be sent due to the connection status.
It is usually not necessary to access this API directly, however if
you are looking at how to read events from a pool of connection, you're most
probably looking for the prelude_connection_pool_check_event()
function.
If this is the case, use prelude_connection_pool_check_event()
for polling the
pool or prelude_connection_set_event_handler()
/ prelude_connection_set_global_event_handler()
if you want asynchronous notification of event.
Note that prelude_connection_set_event_handler()
and prelude_connection_set_global_event_handler()
are only asynchronous if timer are running in asynchronous mode. Otherwise, the callback for theses
function might be called when you call the prelude_timer_wake_up()
function.
In the provided callback, you might use prelude_connection_recv()
to retrieve an event of type
PRELUDE_CONNECTION_POOL_EVENT_INPUT. And, you could, for example, if the retrieved message has
the PRELUDE_MSG_ID_IDMEF tag, provide the returned prelude_msg_t object to idmef_message_read()
in order to convert the received message to a idmef_message_t object.
typedef enum { PRELUDE_CONNECTION_POOL_FLAGS_RECONNECT = 0x01, PRELUDE_CONNECTION_POOL_FLAGS_FAILOVER = 0x02 } prelude_connection_pool_flags_t;
typedef enum { PRELUDE_CONNECTION_POOL_EVENT_INPUT = 0x01, PRELUDE_CONNECTION_POOL_EVENT_DEAD = 0x02, PRELUDE_CONNECTION_POOL_EVENT_ALIVE = 0x04 } prelude_connection_pool_event_t;
void prelude_connection_pool_broadcast (prelude_connection_pool_t *pool, prelude_msg_t *msg);
Sends the message contained in msg
to all the connection in pool
.
|
Pointer to a prelude_connection_pool_t object. |
|
Pointer on a prelude_msg_t object. |
void prelude_connection_pool_broadcast_async (prelude_connection_pool_t *pool, prelude_msg_t *msg);
Sends the message contained in msg
to all connections
in pool
asynchronously. After the request is processed,
the msg
message will be freed.
|
Pointer to a prelude_connection_pool_t object |
|
Pointer on a prelude_msg_t object. |
int prelude_connection_pool_init (prelude_connection_pool_t *pool);
Initializes pool
. This means that connection associated with pool
using prelude_connection_pool_set_connection_string()
will be
established.
|
Pointer to a prelude_connection_pool_t object. |
Returns : |
0 on success, a negative value on error. |
int prelude_connection_pool_new (prelude_connection_pool_t **ret, prelude_client_profile_t *cp, prelude_connection_permission_t permission);
prelude_connection_pool_new()
initializes a new Connection Manager object.
|
Pointer to an address where to store the created prelude_connection_pool_t object. |
|
The prelude_client_profile_t to use for connection. |
|
Permission the connection in this connection-pool will require. |
Returns : |
0 on success or a negative value if an error occured. |
prelude_connection_pool_t * prelude_connection_pool_ref (prelude_connection_pool_t *pool);
Increases pool
reference count.
prelude_connection_pool_destroy()
will decrease the refcount until
it reaches 0, at which point the pool
will be destroyed.
|
Pointer to a prelude_connection_pool_t object. |
Returns : |
The provided pool is returned.
|
prelude_list_t * prelude_connection_pool_get_connection_list (prelude_connection_pool_t *pool);
|
Pointer to a prelude_connection_pool_t object. |
Returns : |
The list of connections handled by pool .
|
int prelude_connection_pool_add_connection (prelude_connection_pool_t *pool, prelude_connection_t *cnx);
Adds cnx
to pool
set of connections.
If pool
is already initialized (prelude_connection_pool_init()
called)
and cnx
is not alive, it will attempt a reconnection.
|
Pointer to a prelude_connection_pool_t object. |
|
Pointer to a prelude_connection_t object to add to pool .
|
Returns : |
0 on success, a negative value if an error occured. |
int prelude_connection_pool_del_connection (prelude_connection_pool_t *pool, prelude_connection_t *cnx);
Remove cnx
from pool
of connections.
|
Pointer to a prelude_connection_pool_t object. |
|
Pointer to a prelude_connection_t object to remove from pool .
|
Returns : |
0 on success, a negative value if an error occured. |
int prelude_connection_pool_set_connection_dead (prelude_connection_pool_t *pool, prelude_connection_t *cnx);
Notifies pool
that the connection identified by cnx
is dead.
Usually, this function should not be used since pool
is
self sufficient, and handles connections issues internally. However,
it is sometime useful when the user has several mechanisms using the
connection, and that its own mechanism detects a connection problem
before pool
notice.
|
Pointer to a prelude_connection_pool_t object. |
|
Pointer to a prelude_connection_t object used within pool .
|
Returns : |
0 on success, a negative value if an error occured. |
int prelude_connection_pool_set_connection_alive (prelude_connection_pool_t *pool, prelude_connection_t *cnx);
Notifies pool
that the connection identified by cnx
went back alive.
Usually, this function should not be used since pool
is
self sufficient, and handles connection issues internally. However,
it is sometime useful when the user has several mechanisms using the
connection, and that its own mechanism detects a connection problem
before pool
notice.
|
Pointer to a prelude_connection_pool_t object. |
|
Pointer to a prelude_connection_t object used within pool .
|
Returns : |
0 on success, a negative value if an error occured. |
int prelude_connection_pool_set_connection_string (prelude_connection_pool_t *pool, const char *cfgstr);
Sets the connection string for pool
. The connection string should be
in the form of : "address". Special operand like || (OR) and && (AND),
are also accepted: "address && address".
Where && means that alert sent using pool
will go to both configured
addresses, and || means that if the left address fails, the right address
will be used.
prelude_connection_pool_init()
should be used to initiates the connection.
|
Pointer to a prelude_connection_pool_t object. |
|
Connection string. |
Returns : |
0 on success, a negative value if an error occured. |
const char * prelude_connection_pool_get_connection_string (prelude_connection_pool_t *pool);
Used to query the connection string used by pool
.
|
Pointer to a prelude_connection_pool_t object. |
Returns : |
The connection string. |
void prelude_connection_pool_destroy (prelude_connection_pool_t *pool);
Destroys pool
and all connections handled.
|
Pointer to a prelude_connection_pool_t object. |
prelude_connection_pool_flags_t prelude_connection_pool_get_flags (prelude_connection_pool_t *pool);
|
Pointer to a prelude_connection_pool_t object. |
Returns : |
the prelude_connection_pool_flags_t used in pool .
|
void prelude_connection_pool_set_flags (prelude_connection_pool_t *pool, prelude_connection_pool_flags_t flags);
Sets flags
within pools
.
|
Pointer to a prelude_connection_pool_t object. |
|
Flags to use for pool .
|
void prelude_connection_pool_set_required_permission (prelude_connection_pool_t *pool, prelude_connection_permission_t req_perm);
|
|
|
void prelude_connection_pool_set_data (prelude_connection_pool_t *pool, void *data);
The user might use this function to associate data with pool
.
The data associated might be retrieved using prelude_connection_pool_get_data()
.
|
Pointer to a prelude_connection_pool_t object. |
|
Pointer to user specific data. |
void * prelude_connection_pool_get_data (prelude_connection_pool_t *pool);
The user might use this function to query data associated with
pool
using prelude_connection_pool_set_data()
.
|
Pointer to a prelude_connection_pool_t object. |
Returns : |
the user data associated to pool .
|
int prelude_connection_pool_recv (prelude_connection_pool_t *pool, int timeout, prelude_connection_t **outcon, prelude_msg_t **outmsg);
This function queries the set of connections available in pool
to see if
events are waiting to be handled. If timeout is zero, then this function
will return immediatly in case there is no event to be handled.
If timeout is -1, this function won't return until an event is available. Otherwise this function will return if there is no event after the specified number of second.
If an event is available, it will be read and store the prelude_connection_t
object in the outcon
pointer. If outmsg
was specified, the message will be
read and stored in there.
|
Pointer to a prelude_connection_pool_t object. |
|
Time to wait for an event. |
|
Pointer where the connection where an event happened should be stored. |
|
Pointer where the next message that will be read should be stored. |
Returns : |
The number of handled events (0 or 1) or a negative value if an error occured. |
int prelude_connection_pool_check_event (prelude_connection_pool_t *pool, int timeout, int (event_cbprelude_connection_pool_t *pool,prelude_connection_pool_event_t event,prelude_connection_t *cnx, void *extra) (), void *extra);
This function queries the set of connections available in pool
to see if
events are waiting to be handled. If timeout is zero, then this function
will return immediatly in case there is no event to be handled.
If timeout is -1, this function won't return until an event is available. Otherwise this function will return if there is no event after the specified number of second.
For each event, event_cb
is called with the concerned pool
, the provided
extra
data, and the cnx
where an event has occured.
|
Pointer to a prelude_connection_pool_t object. |
|
Time to wait for an event. |
|
User provided callback function to call on received events. |
|
Pointer to user specific data provided to event_cb .
|
Returns : |
The number of handled events, or a negative value if an error occured. |
void prelude_connection_pool_set_global_event_handler (prelude_connection_pool_t *pool, prelude_connection_pool_event_t wanted_events, int (callbackprelude_connection_pool_t *pool,prelude_connection_pool_event_t events) ());
callback
will be called each time one of the event specified in
wanted_events
happen to pool
. However, contrary to
prelude_connection_pool_set_event_handler()
, the callback will be called
only once per set of event.
|
Pointer to a prelude_connection_pool_t object. |
|
Event the user want to be notified about. |
|
User specific callback to call when an event is available. |
void prelude_connection_pool_set_event_handler (prelude_connection_pool_t *pool, prelude_connection_pool_event_t wanted_events, int (callbackprelude_connection_pool_t *pool,prelude_connection_pool_event_t events,prelude_connection_t *cnx) ());
callback
will be called each time one of the event specified in
wanted_events
happens to pool
.
|
Pointer to a prelude_connection_pool_t object. |
|
Event the user want to be notified about. |
|
User specific callback to call when an event is available. |