idmef-path

## idmef-path idmef-path — The High level IDMEF API. |

## Synopsis

    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,
                                                             unsigned 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,
                                                             unsigned 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,
                                                             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.

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

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

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

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

`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,
                                                             unsigned 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,
                                                             unsigned 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.