idmef-path

idmef-path — The High level IDMEF API.

Functions

Types and Values

typedef idmef_path_t

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

Functions

idmef_path_get ()

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.

Parameters

path

Pointer to a idmef_path_t object.

 

message

Pointer to a idmef_message_t 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,
                idmef_message_t *message,
                idmef_value_t *value);

This function sets the provided value for path within message .

Parameters

path

Pointer to a idmef_path_t object.

 

message

Pointer to a idmef_message_t 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 .

Parameters

path

Address where to store the created idmef_path_t object.

 

format

Format string.

 

...

Arguments list.

 

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,
                  va_list args);

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

Parameters

path

Address where to store the created idmef_path_t object.

 

format

Format string.

 

args

Pointer to a variable argument list.

 

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Returns


idmef_path_get_depth ()

unsigned int
idmef_path_get_depth (const idmef_path_t *path);

Parameters

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 .

Parameters

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 .

Parameters

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.

Types and Values

idmef_path_t

typedef struct idmef_path idmef_path_t;

See Also

idmef_value_t for setting idmef_path_t value.