idmef-path

idmef-path — The High level IDMEF API.

Synopsis

typedef             idmef_path_t;
int                 idmef_path_get                      (const idmef_path_t *path,
                                                         void *object,
                                                         idmef_value_t **ret);
int                 idmef_path_set                      (const idmef_path_t *path,
                                                         void *object,
                                                         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);
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);

Description

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");

Details

idmef_path_t

typedef struct idmef_path idmef_path_t;

idmef_path_get ()

int                 idmef_path_get                      (const idmef_path_t *path,
                                                         void *object,
                                                         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.

path :

 Pointer to a idmef_path_t object.

object :

ret :

 Address where to store the retrieved idmef_value_t.

Returns :

 The number of element retrieved, or a negative value if an error occured.

idmef_path_set ()

int                 idmef_path_set                      (const idmef_path_t *path,
                                                         void *object,
                                                         idmef_value_t *value);

This function sets the provided value for path within message.

path :

 Pointer to a idmef_path_t object.

object :

value :

 Pointer to a idmef_value_t object.

Returns :

 0 on success, a negative value if an error occured.

idmef_path_new ()

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.

path :

 Address where to store the created idmef_path_t object.

format :

 Format string.

Returns :

 0 on success, or a negative value if an error occured.

idmef_path_new_v ()

int                 idmef_path_new_v                    (idmef_path_t **path,
                                                         const char *format);

Creates an idmef_path_t object pointing to the provided format string format and args, and stores it within path.

path :

 Address where to store the created idmef_path_t object.

format :

 Format string.

Returns :

 0 on success, or a negative value if an error occured.

idmef_path_new_fast ()

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.

path :

 Address where to store the created idmef_path_t object.

buffer :

 Name of the path to create.

Returns :

 0 on success, or a negative value if an error occured.

idmef_path_get_class ()

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.

path :

 Pointer to an idmef_path_t object.

depth :

 Depth of path to 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_path_get_value_type ()

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.

path :

 Pointer to an idmef_path_t object.

depth :

 Depth of path to 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.

idmef_path_set_index ()

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.

path :

 Pointer to an idmef_path_t object.

depth :

 Depth of path to set index for.

index :

 Index for the provided element depth.

Returns :

 0 on success, a negative value if an error occured.

idmef_path_undefine_index ()

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.

path :

 Pointer to an idmef_path_t object.

depth :

 Depth of path to undefine the index for.

Returns :

 0 on success, a negative value if an error occured.

idmef_path_get_index ()

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.

path :

 Pointer to an idmef_path_t object.

depth :

 Depth of path to retrieve the index from.

Returns :

 The element index, or a negative value if an error occured.

idmef_path_make_child ()

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.

path :

 Pointer to an idmef_path_t object.

child_name :

 Name of the child element to create.

index :

 Index for child_name, if applicable.

Returns :

 0 on success, or a negative value if an error occured.

idmef_path_make_parent ()

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.

path :

 Pointer to an idmef_path_t object.

Returns :

 0 on success, or a negative value if an error occured.

idmef_path_destroy ()

void                idmef_path_destroy                  (idmef_path_t *path);

Destroys the provided path object.

path :

 Pointer to an idmef_path_t object.

idmef_path_ncompare ()

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.

p1 :

 Pointer to an idmef_path_t object.

p2 :

 Pointer to another idmef_path_t object.

depth :

 Maximum depth to use for path comparison.

Returns :

 0 if both element match, a negative value otherwise.

idmef_path_compare ()

int                 idmef_path_compare                  (const idmef_path_t *p1,
                                                         const idmef_path_t *p2);

Compares p1 and p2 elements.

p1 :

 Pointer to an idmef_path_t object.

p2 :

 Pointer to another idmef_path_t object.

Returns :

 0 if both element match, a negative value otherwise.

idmef_path_clone ()

int                 idmef_path_clone                    (const idmef_path_t *src,
                                                         idmef_path_t **dst);

Clones src and stores the result in the provided dst address.

src :

 Pointer to an idmef_path_t object.

dst :

 Address where to store the copy of src.

Returns :

 0 on success, a negative value otherwise.

idmef_path_ref ()

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.

path :

 Pointer to an idmef_path_t object.

Returns :

 The provided path is returned.

idmef_path_get_name ()

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

path :

 Pointer to an idmef_path_t object.

depth :

 Depth of the path element to get the name from.

Returns :

 path name relative to the provided dept.

idmef_path_is_ambiguous ()

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.

path :

 Pointer to an idmef_path_t object.

Returns :

 TRUE if the object is ambiguous, FALSE otherwise.

idmef_path_has_lists ()

int                 idmef_path_has_lists                (const idmef_path_t *path);

path :

 Pointer to an idmef_path_t object.

Returns :

 the number of listed element within path.

idmef_path_is_list ()

prelude_bool_t      idmef_path_is_list                  (const idmef_path_t *path,
                                                         int depth);

path :

depth :

Returns :

idmef_path_get_depth ()

unsigned int        idmef_path_get_depth                (const idmef_path_t *path);

path :

 Pointer to an idmef_path_t object.

Returns :

 depth number of elements.

idmef_path_check_operator ()

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.

path :

 Pointer to a idmef_path_t object.

op :

 Operator to check compatibility with.

Returns :

 0 on success, a negative value if an error occured.

idmef_path_get_applicable_operators ()

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.

path :

 Pointer to a idmef_path_t object.

result :

 Pointer to storage for applicable operator.

Returns :

 0 on success, a negative value if an error occured.

See Also

idmef_value_t for setting idmef_path_t value.

Generated by GTK-Doc V1.11