|  |  |  | Prelude library Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | ||||
typedef idmef_path_t; int idmef_path_get (const idmef_path_t *path, idmef_message_t *message, idmef_value_t **ret); int idmef_path_set (const idmef_path_t *path, idmef_message_t *message, idmef_value_t *value); int idmef_path_new (idmef_path_t **path, const char *format, ...); int idmef_path_new_v (idmef_path_t **path, const char *format, va_list args); int idmef_path_new_fast (idmef_path_t **path, const char *buffer); idmef_class_id_t idmef_path_get_class (const idmef_path_t *path, int depth); idmef_value_type_id_t idmef_path_get_value_type (const idmef_path_t *path, int depth); int idmef_path_set_index (idmef_path_t *path, unsigned int depth, int index); int idmef_path_undefine_index (idmef_path_t *path, unsigned int depth); int idmef_path_get_index (const idmef_path_t *path, unsigned int depth); int idmef_path_make_child (idmef_path_t *path, const char *child_name, int index); int idmef_path_make_parent (idmef_path_t *path); void idmef_path_destroy (idmef_path_t *path); int idmef_path_ncompare (const idmef_path_t *p1, const idmef_path_t *p2, unsigned int depth); int idmef_path_compare (const idmef_path_t *p1, const idmef_path_t *p2); int idmef_path_clone (const idmef_path_t *src, idmef_path_t **dst); idmef_path_t * idmef_path_ref (idmef_path_t *path); const char * idmef_path_get_name (const idmef_path_t *path, int depth); prelude_bool_t idmef_path_is_ambiguous (const idmef_path_t *path); int idmef_path_has_lists (const idmef_path_t *path); prelude_bool_t idmef_path_is_list (const idmef_path_t *path, int depth); unsigned int idmef_path_get_depth (const idmef_path_t *path); int idmef_path_check_operator (const idmef_path_t *path, idmef_criterion_operator_t op); int idmef_path_get_applicable_operators (const idmef_path_t *path, idmef_criterion_operator_t *result);
The IDMEF path API provide a methodes to define a "path" in the IDMEF tree. Once this path is defined, the user might set or retrieve this path.
Here is an example of how to use this API in order to set a given path within a idmef_message_t root object:
First, we need to create a path to the object we want to create. If for example, we wish to create the alert.classification.text path within our message, we will use:
int ret;
idmef_path_t *path;
ret = idmef_path_new(&path, "alert.classification.text");
if ( ret < 0 )
        return ret;
Using the above, we just created a "pointer" to a given path in our idmef_message_t. This path doesn't yet exist, but might be used to read, or to write a value.
int ret;
idmef_value_t *value;
ret = idmef_value_new_from_path(&value, path, "A value");
if ( ret < 0 )
        return ret;
Here we just created a value applicable to the previously created path. That is, if our path is pointing to a value of type string, the created idmef_value_t object will be of this type.
idmef_message_t *idmef; /* * create our top message */ ret = idmef_message_new(&idmef); /* * Set the previously defined path to the previously created value * in the top level idmef message 'idmef'. */ ret = idmef_path_set(path, idmef, value);
And finally, we create our top level idmef_message_t object and set the created idmef_value_t as the value for our created idmef_path_t.
Given our previous example, we can write the following function:
static int set_idmef_path(idmef_message_t *message, const char *pathname, const char *value)
{
        int ret;
        idmef_value_t *val;
        idmef_path_t *path;
        ret = idmef_path_new(&path, pathname);
        if ( ret < 0 )
                return ret;
        ret = idmef_value_new_from_path(&val, path, value);
        if ( ret < 0 ) {
                idmef_path_destroy(path);
                return ret;
        }
        ret = idmef_path_set(path, message, val);
        idmef_value_destroy(val);
        idmef_path_destroy(path);
        return ret;
}
You will then be able to set any field of the IDMEF message using:
idmef_message_t *idmef;
ret = idmef_message_new(&idmef);
if ( ret < 0 )
        return ret;
set_idmef_path(idmef, "alert.classification.text", "My classification text");
set_idmef_path(idmef, "alert.classification.reference(0).name", "OSVDB-XXXX");
set_idmef_path(idmef, "alert.classification.reference(0).origin", "osvdb");
set_idmef_path(idmef, "alert.classification.reference(0).url", "http://my.url/");
set_idmef_path(idmef, "alert.source(0).node.address(0).address", "127.0.0.1");
int idmef_path_get (const idmef_path_t *path, idmef_message_t *message, idmef_value_t **ret);
This function retrieves the value for path within message,
and stores it into the provided ret address of type idmef_value_t.
| 
 | Pointer to a idmef_path_t object. | 
| 
 | Pointer to a idmef_message_t object. | 
| 
 | Address where to store the retrieved idmef_value_t. | 
| Returns : | The number of element retrieved, or a negative value if an error occured. | 
int idmef_path_set (const idmef_path_t *path, idmef_message_t *message, idmef_value_t *value);
This function sets the provided value for path within message.
| 
 | Pointer to a idmef_path_t object. | 
| 
 | Pointer to a idmef_message_t object. | 
| 
 | Pointer to a idmef_value_t object. | 
| Returns : | 0 on success, a negative value if an error occured. | 
int idmef_path_new (idmef_path_t **path, const char *format, ...);
Creates an idmef_path_t object pointing to the provided format
string format and @..., and stores it within path.
| 
 | Address where to store the created idmef_path_t object. | 
| 
 | Format string. | 
| 
 | Arguments list. | 
| Returns : | 0 on success, or a negative value if an error occured. | 
int idmef_path_new_v (idmef_path_t **path, const char *format, va_list args);
Creates an idmef_path_t object pointing to the provided format
string format and args, and stores it within path.
| 
 | Address where to store the created idmef_path_t object. | 
| 
 | Format string. | 
| 
 | Pointer to a variable argument list. | 
| Returns : | 0 on success, or a negative value if an error occured. | 
int idmef_path_new_fast (idmef_path_t **path, const char *buffer);
Creates a idmef_path_t object pointing to buffer, and stores it within path.
| 
 | Address where to store the created idmef_path_t object. | 
| 
 | Name of the path to create. | 
| Returns : | 0 on success, or a negative value if an error occured. | 
idmef_class_id_t idmef_path_get_class (const idmef_path_t *path, int depth);
Retrieves the idmef_class_id_t value for the element of path
located at depth. If depth is -1, the last element depth is addressed.
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Depth of pathto retrieve the idmef_class_id_t from. | 
| Returns : | The idmef_class_id_t for the elemnt, or a negative value if an error occured. | 
idmef_value_type_id_t idmef_path_get_value_type (const idmef_path_t *path, int depth);
Retrieves the idmef_value_type_id_t identifying the type of value
acceptable for this path element, for the path element located at
depth. If depth is -1, the last element depth is addressed.
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Depth of pathto retrieve the idmef_value_type_id_t from. | 
| Returns : | The idmef_value_type_id_t for the element, or a negative value if an error occured. | 
int idmef_path_set_index (idmef_path_t *path, unsigned int depth, int index);
Modifies index for the element located at depth of provided path.
This function is only applicable for element that accept listed value.
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Depth of pathto setindexfor. | 
| 
 | Index for the provided element depth. | 
| Returns : | 0 on success, a negative value if an error occured. | 
int idmef_path_undefine_index (idmef_path_t *path, unsigned int depth);
Modifies the element located at depth of provided path so that it's
index is undefined.
This function is only applicable for element that accept listed value.
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Depth of pathto undefine the index for. | 
| Returns : | 0 on success, a negative value if an error occured. | 
int idmef_path_get_index (const idmef_path_t *path, unsigned int depth);
Gets the current index for element located at depth of path.
This function is only applicable for element that accepts listed value.
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Depth of pathto retrieve the index from. | 
| Returns : | The element index, or a negative value if an error occured. | 
int idmef_path_make_child (idmef_path_t *path, const char *child_name, int index);
Modifies path so that it points to the child node identified by child_name,
children of the current path. That is if the path is currently pointing to
alert.classification, and child_name is set to "text", path will be
modified to point to alert.classification.text.
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Name of the child element to create. | 
| 
 | Index for child_name, if applicable. | 
| Returns : | 0 on success, or a negative value if an error occured. | 
int idmef_path_make_parent (idmef_path_t *path);
Removes the last element of the path. That is, if path is currently pointing to
alert.classification, path will be modified to point to alert.
| 
 | Pointer to an idmef_path_t object. | 
| Returns : | 0 on success, or a negative value if an error occured. | 
void idmef_path_destroy (idmef_path_t *path);
Destroys the provided path object.
| 
 | Pointer to an idmef_path_t object. | 
int idmef_path_ncompare (const idmef_path_t *p1, const idmef_path_t *p2, unsigned int depth);
Compares p1 and p2 elements up to depth.
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Pointer to another idmef_path_t object. | 
| 
 | Maximum depth to use for path comparison. | 
| Returns : | 0 if both element match, a negative value otherwise. | 
int idmef_path_compare (const idmef_path_t *p1, const idmef_path_t *p2);
Compares p1 and p2 elements.
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Pointer to another idmef_path_t object. | 
| Returns : | 0 if both element match, a negative value otherwise. | 
int idmef_path_clone (const idmef_path_t *src, idmef_path_t **dst);
Clones src and stores the result in the provided dst address.
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Address where to store the copy of src. | 
| Returns : | 0 on success, a negative value otherwise. | 
idmef_path_t * idmef_path_ref (idmef_path_t *path);
Increases path reference count.
idmef_path_destroy() will destroy the refcount until it reaches 0,
at which point the path will be destroyed.
| 
 | Pointer to an idmef_path_t object. | 
| Returns : | The provided pathis returned. | 
const char * idmef_path_get_name (const idmef_path_t *path, int depth);
Returns the full path name if the provided depth is -1, or the specific
element name if depth is set. That is, for a path pointing to
"alert.classification.text": A depth of -1 would return "alert.classification.text";
a depth of 0 would return "alert"; a depth of 1 would return "classification"; and
a depth of 2 would return "text".
| 
 | Pointer to an idmef_path_t object. | 
| 
 | Depth of the pathelement to get the name from. | 
| Returns : | pathname relative to the provideddept. | 
prelude_bool_t idmef_path_is_ambiguous (const idmef_path_t *path);
Returns TRUE if path contain elements that are supposed
to be listed, but for which no index were provided.
| 
 | Pointer to an idmef_path_t object. | 
| Returns : | TRUE if the object is ambiguous, FALSE otherwise. | 
int idmef_path_has_lists (const idmef_path_t *path);
| 
 | Pointer to an idmef_path_t object. | 
| Returns : | the number of listed element within path. | 
prelude_bool_t idmef_path_is_list (const idmef_path_t *path, int depth);
| 
 | |
| 
 | |
| Returns : | 
unsigned int idmef_path_get_depth (const idmef_path_t *path);
| 
 | Pointer to an idmef_path_t object. | 
| Returns : | depthnumber of elements. | 
int idmef_path_check_operator (const idmef_path_t *path, idmef_criterion_operator_t op);
Check whether op can apply to value pointed to by path.
| 
 | Pointer to a idmef_path_t object. | 
| 
 | Operator to check compatibility with. | 
| Returns : | 0 on success, a negative value if an error occured. | 
int idmef_path_get_applicable_operators (const idmef_path_t *path, idmef_criterion_operator_t *result);
Retrieve all applicable operator that might be used by the type of
value pointed to by path.
| 
 | Pointer to a idmef_path_t object. | 
| 
 | Pointer to storage for applicable operator. | 
| Returns : | 0 on success, a negative value if an error occured. |