## prelude-client

prelude-client

## Functions

prelude_ident_t * | prelude_client_get_unique_ident ()
void | prelude_client_set_connection_pool ()
prelude_connection_pool_t * | prelude_client_get_connection_pool ()
int | prelude_client_start ()
int | prelude_client_init ()
int | prelude_client_new ()
prelude_client_t * | prelude_client_ref ()
idmef_analyzer_t * | prelude_client_get_analyzer ()
prelude_client_flags_t | prelude_client_get_flags ()
void | prelude_client_set_required_permission ()
prelude_connection_permission_t | prelude_client_get_required_permission ()
void | prelude_client_send_msg ()
int | prelude_client_recv_msg ()
void | prelude_client_set_heartbeat_cb ()
void | prelude_client_send_idmef ()
int | prelude_client_recv_idmef ()
void | prelude_client_destroy ()
int | prelude_client_set_flags ()
int | prelude_client_set_config_filename ()
const char * | prelude_client_get_config_filename ()
prelude_bool_t | prelude_client_is_setup_needed ()
prelude_client_profile_t * | prelude_client_get_profile ()
int | prelude_client_new_msgbuf ()
int | prelude_client_handle_msg_default ()
const char * | prelude_client_get_setup_error ()
void | prelude_client_print_setup_error ()

## Types and Values

enum | prelude_client_exit_status_t
enum | prelude_client_flags_t
typedef | prelude_client_t

## Description

## Functions

### prelude_client_get_unique_ident ()

    prelude_ident_t *
    prelude_client_get_unique_ident (prelude_client_t *client);

### prelude_client_set_connection_pool ()

    void
    prelude_client_set_connection_pool (prelude_client_t *client,
                                        prelude_connection_pool_t *pool);

Use this function in order to set your own list of peer that `client` should send message too. This might be usefull in case you don't want this to be automated by `prelude_client_init()`.

#### Parameters

client | pointer to a prelude_client_t object. |
pool | pointer to a prelude_client_pool_t object. |

### prelude_client_get_connection_pool ()

    prelude_connection_pool_t *
    prelude_client_get_connection_pool (prelude_client_t *client);

Return a pointer to the prelude_connection_pool_t object used by `client` to send messages.

#### Parameters

client | pointer to a prelude_client_t object. |

#### Returns

a pointer to a prelude_connection_pool_t object.

### prelude_client_start ()

    int
    prelude_client_start (prelude_client_t *client);

This function start the `client` object, triggering a connection from the client to it's server if any were specified, and sending the initial `client` heartbeat.

If `client` was not initialized, then `prelude_client_init()` will be called and thus this function might fail if the client was not registered.

#### Parameters

client | Pointer to a client object to initialize. |

#### Returns

0 on success, -1 if an error occured.

### prelude_client_init ()

    int
    prelude_client_init (prelude_client_t *client);

This function initialize the `client` object, meaning reading generic options from the `prelude_client_new()` provided configuration file and the array of arguments specified through `prelude_init()`.

Calling this function is optional and should be done only if you need more granularity between `prelude_client_new()` and `prelude_client_start()`:

prelude_client_start() will call `prelude_client_init()` for you if needed.

#### Parameters

client | Pointer to a prelude_client_t object to initialize. |

#### Returns

0 on success, -1 if an error occured.

### prelude_client_new ()

    int
    prelude_client_new (prelude_client_t **client,
                        const char *profile);

This function initialize the `client` object.

#### Parameters

client | Pointer to a client object to initialize. |
profile | Default profile name for this analyzer. |

#### Returns

0 on success or a negative value if an error occur.

### prelude_client_ref ()

    prelude_client_t *
    prelude_client_ref (prelude_client_t *client);

### prelude_client_get_analyzer ()

    idmef_analyzer_t *
    prelude_client_get_analyzer (prelude_client_t *client);

Provide access to the idmef_analyzer_t object associated to `client` . This analyzer object is sent along with every alerts and heartbeats emited by this client. The analyzer object is created by `prelude_client_init()`.

#### Parameters

client | Pointer to a prelude_client_t object. |

#### Returns

the idmef_analyzer_t object associated with `client` .

### prelude_client_get_flags ()

    prelude_client_flags_t
    prelude_client_get_flags (prelude_client_t *client);

Get flags set through `prelude_client_set_flags()`.

#### Parameters

client | Pointer on a prelude_client_t object. |

#### Returns

an or'ed list of prelude_client_flags_t.

### prelude_client_set_required_permission ()

    void
    prelude_client_set_required_permission
                                   (prelude_client_t *client,
                                    prelude_connection_permission_t permission);

Set the required `permission` for `client` . The default is PRELUDE_CONNECTION_PERMISSION_IDMEF_WRITE | PRELUDE_CONNECTION_PERMISSION_ADMIN_READ. Value set through this function should be set before `prelude_client_start()`.

If the client certificate for connecting to one of the specified manager doesn't have theses permission the client will reject the certificate and ask for registration.

#### Parameters

client | Pointer on a prelude_client_t object. |
permission | Required permission for `client` . |

### prelude_client_get_required_permission ()

    prelude_connection_permission_t
    prelude_client_get_required_permission
                                   (prelude_client_t *client);

#### Parameters

client | Pointer on a prelude_client_t object. |

#### Returns

`client` permission as set with `prelude_client_set_required_permission()`

### prelude_client_send_msg ()

    void
    prelude_client_send_msg (prelude_client_t *client,
                             prelude_msg_t *msg);

Send `msg` to the peers `client` is communicating with.

The message will be sent asynchronously if `PRELUDE_CLIENT_FLAGS_ASYNC_SEND` was set using `prelude_client_set_flags()` in which case the caller should not call `prelude_msg_destroy()` on `msg` .

#### Parameters

client | Pointer to a prelude_client_t object. |
msg | pointer to a message that `client` should send. |

### prelude_client_recv_msg ()

    int
    prelude_client_recv_msg (prelude_client_t *client,
                             int timeout,
                             prelude_msg_t **msg);

Wait `timeout` second for a message on `client` connection pool.

A `timeout` of -1, mean `prelude_client_recv_msg()` will block until a message is received. A `timeout` of 0 mean that it will return immediatly.

#### Parameters

client | Pointer to a prelude_client_t object. |
timeout | Number of millisecond to wait for a message. |
msg | Pointer where the received prelude_msg_t should be stored. |

#### Returns

0 on timeout, a negative value on error, 1 on success.

### prelude_client_set_heartbeat_cb ()

    void
    prelude_client_set_heartbeat_cb (prelude_client_t *client,
                                     void (*cb) (prelude_client_t *client, idmef_message_t *hb));

Use if you want to override the default function used to automatically send heartbeat to `client` peers.

#### Parameters

client | pointer to a prelude_client_t object. |
cb | pointer to a function handling heartbeat sending. |

### prelude_client_send_idmef ()

    void
    prelude_client_send_idmef (prelude_client_t *client,
                               idmef_message_t *msg);

Send `msg` to the peers `client` is communicating with.

The message will be sent asynchronously if `PRELUDE_CLIENT_FLAGS_ASYNC_SEND` was set using `prelude_client_set_flags()`.

#### Parameters

client | Pointer to a prelude_client_t object. |
msg | pointer to an IDMEF message to be sent to `client` peers. |

### prelude_client_recv_idmef ()

    int
    prelude_client_recv_idmef (prelude_client_t *client,
                               int timeout,
                               idmef_message_t **idmef);

Wait `timeout` second for a message on `client` connection pool.

A `timeout` of -1, mean `prelude_client_recv_idmef()` will block until a message is received. A `timeout` of 0 mean that it will return immediatly.

#### Parameters

client | Pointer to a prelude_client_t object. |
timeout | Number of second to wait for a message. |
idmef | Pointer where the received idmef_message_t should be stored. |

#### Returns

0 on timeout, a negative value on error, 1 on success.

### prelude_client_destroy ()

    void
    prelude_client_destroy (prelude_client_t *client,
                            prelude_client_exit_status_t status);

Destroy `client` , and send an heartbeat containing the 'exiting' status in case `status` is PRELUDE_CLIENT_EXIT_STATUS_SUCCESS.

This is useful for analyzer expected to be running periodically, and that shouldn't be treated as behaving anormaly in case no heartbeat is sent.

Please note that your are not supposed to run this function from a signal handler.

#### Parameters

client | Pointer on a client object. |
status | Exit status for the client. |

### prelude_client_set_flags ()

    int
    prelude_client_set_flags (prelude_client_t *client,
                              prelude_client_flags_t flags);

Set specific flags in the `client` structure. This function can be called anytime after the creation of the `client` object.

When settings asynchronous flags such as PRELUDE_CLIENT_FLAGS_ASYNC_SEND or PRELUDE_CLIENT_FLAGS_ASYNC_TIMER, be carefull to call `prelude_client_set_flags()` in the same process you want to use the asynchronous API from. Threads aren't copied accross `fork()`.

#### Parameters

client | Pointer on a prelude_client_t object. |
flags | Or'd list of flags used by `client` . |

#### Returns

0 if setting `flags` succeed, -1 otherwise.

### prelude_client_set_config_filename ()

    int
    prelude_client_set_config_filename (prelude_client_t *client,
                                        const char *filename);

The default for a client is to use a template configuration file (idmef-client.conf). By using this function you might override the default and provide your own configuration file to use for `client` . The format of the configuration file need to be compatible with the Prelude format.

#### Parameters

client | pointer on a prelude_client_t object. |
filename | Configuration file to use for this client. |

#### Returns

0 on success, -1 if an error occured.

### prelude_client_get_config_filename ()

    const char *
    prelude_client_get_config_filename (prelude_client_t *client);

Return the filename where `client` configuration is stored. This filename is originally set by the `prelude_client_new()` function.

#### Parameters

client | pointer on a prelude_client_t object. |

#### Returns

a pointer to `client` configuration filename.

### prelude_client_is_setup_needed ()

    prelude_bool_t
    prelude_client_is_setup_needed (int error);

`prelude_client_is_setup_needed` is deprecated and should not be used in newly-written code.

use standard error API.

This function should be called as a result of an error by the `prelude_client_start()` function, to know if the analyzer need to be registered.

#### Parameters

error | Error returned by `prelude_client_start()`. |

#### Returns

TRUE if setup is needed, FALSE otherwise.

### prelude_client_get_profile ()

    prelude_client_profile_t *
    prelude_client_get_profile (prelude_client_t *client);

### prelude_client_new_msgbuf ()

    int
    prelude_client_new_msgbuf (prelude_client_t *client,
                               prelude_msgbuf_t **msgbuf);

### prelude_client_handle_msg_default ()

    int
    prelude_client_handle_msg_default (prelude_client_t *client,
                                       prelude_msg_t *msg,
                                       prelude_msgbuf_t *msgbuf);

### prelude_client_get_setup_error ()

    const char *
    prelude_client_get_setup_error (prelude_client_t *client);

`prelude_client_get_setup_error` is deprecated and should not be used in newly-written code.

### prelude_client_print_setup_error ()

    void
    prelude_client_print_setup_error (prelude_client_t *client);

## Types and Values

### enum prelude_client_exit_status_t

#### Members

PRELUDE_CLIENT_EXIT_STATUS_SUCCESS |  |
PRELUDE_CLIENT_EXIT_STATUS_FAILURE |  |

### enum prelude_client_flags_t

#### Members

PRELUDE_CLIENT_FLAGS_ASYNC_SEND |  |
PRELUDE_CLIENT_FLAGS_ASYNC_TIMER |  |
PRELUDE_CLIENT_FLAGS_HEARTBEAT |  |
PRELUDE_CLIENT_FLAGS_CONNECT |  |
PRELUDE_CLIENT_FLAGS_AUTOCONFIG |  |

### prelude_client_t

    typedef struct prelude_client prelude_client_t;