idmef-path: libprelude Reference Manual

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

## Functions

int | idmef_path_get ()
int | idmef_path_set ()
int | idmef_path_new ()
int | idmef_path_new_v ()
int | idmef_path_new_fast ()
idmef_class_id_t | idmef_path_get_class ()
idmef_value_type_id_t | idmef_path_get_value_type ()
int | idmef_path_set_index ()
int | idmef_path_undefine_index ()
int | idmef_path_get_index ()
int | idmef_path_make_child ()
int | idmef_path_make_parent ()
void | idmef_path_destroy ()
int | idmef_path_ncompare ()
int | idmef_path_compare ()
int | idmef_path_clone ()
idmef_path_t * | idmef_path_ref ()
const char * | idmef_path_get_name ()
prelude_bool_t | idmef_path_is_ambiguous ()
int | idmef_path_has_lists ()
prelude_bool_t | idmef_path_is_list ()
unsigned int | idmef_path_get_depth ()
int | idmef_path_check_operator ()
int | idmef_path_get_applicable_operators ()

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

#### Parameters

path | Pointer to a idmef_path_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,
                    void *object,
                    idmef_value_t *value);

This function sets the provided `value` for `path` within `message` .

#### Parameters

path | Pointer to a idmef_path_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);

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

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