idmef-time

## idmef-time idmef-time — Time representation in IDMEF message |

## Synopsis

    typedef             idmef_time_t;
    idmef_time_t *      idmef_time_ref                      (idmef_time_t *time);
    int                 idmef_time_new                      (idmef_time_t **time);
    int                 idmef_time_new_from_time            (idmef_time_t **time,
                                                             const time_t *t);
    int                 idmef_time_new_from_gettimeofday    (idmef_time_t **time);
    int                 idmef_time_new_from_string          (idmef_time_t **time,
                                                             const char *buf);
    int                 idmef_time_new_from_ntpstamp        (idmef_time_t **time,
                                                             const char *buf);
    int                 idmef_time_new_from_timeval         (idmef_time_t **time,
                                                             const struct timeval *tv);
    void                idmef_time_set_from_time            (idmef_time_t *time,
                                                             const time_t *t);
    int                 idmef_time_set_from_gettimeofday    (idmef_time_t *time);
    int                 idmef_time_set_from_string          (idmef_time_t *time,
                                                             const char *buf);
    int                 idmef_time_set_from_ntpstamp        (idmef_time_t *time,
                                                             const char *buf);
    int                 idmef_time_set_from_timeval         (idmef_time_t *time,
                                                             const struct timeval *tv);
    void                idmef_time_destroy_internal         (idmef_time_t *time);
    void                idmef_time_destroy                  (idmef_time_t *time);
    int                 idmef_time_clone                    (const idmef_time_t *src,
                                                             idmef_time_t **dst);
    int                 idmef_time_copy                     (const idmef_time_t *src,
                                                             idmef_time_t *dst);
    void                idmef_time_set_sec                  (idmef_time_t *time,
                                                             uint32_t sec);
    void                idmef_time_set_usec                 (idmef_time_t *time,
                                                             uint32_t usec);
    void                idmef_time_set_gmt_offset           (idmef_time_t *time,
                                                             int32_t gmtoff);
    uint32_t            idmef_time_get_sec                  (const idmef_time_t *time);
    uint32_t            idmef_time_get_usec                 (const idmef_time_t *time);
    int32_t             idmef_time_get_gmt_offset           (const idmef_time_t *time);
    int                 idmef_time_to_string                (const idmef_time_t *time,
                                                             prelude_string_t *out);
    int                 idmef_time_to_ntpstamp              (const idmef_time_t *time,
                                                             prelude_string_t *out);

## Description

The idmef_time_t type is used in order to represent a time value in an IDMEF message. This object contain information such as the number of seconds since the Epoch, the local GMT offset, the number of micro second (if applicable).

When creating an IDMEF message, you need to insert a timestamp in it. IDMEF provide differents time field to be used for this:

- AnalyzerTime

  The AnalyzerTime class is used to indicate the current date and time on the analyzer. Its values should be filled in as late as possible in the message transmission process, ideally immediately before placing the message "on the wire."

- CreateTime

  The CreateTime class is used to indicate the date and time the alert or heartbeat was created by the analyzer.

- DetectTime

  The DetectTime class is used to indicate the date and time the event(s) producing an alert was detected by the analyzer. In the case of more than one event, the time the first event was detected. (This may or may not be the same time as CreateTime; analyzers are not required to send alerts immediately upon detection).

You don't need to take care of the AnalyzerTime field, since in Prelude, once an events is handed to the library, and if the sending of the message fail, there will be a fallback to backuping the event for later retransmission. Thus the library has to take care of setting the AnalyzerTime for you (since the message might not be emited immediatly in this specific case.

Several helper are available in order to create idmef_time_t object. Most probably, the function that you will need are the one bellow:

- `idmef_time_new_from_gettimeofday()` and `idmef_time_set_from_gettimeofday()`
- `idmef_time_new_from_timeval()` and `idmef_time_set_from_timeval()`
- `idmef_time_new_from_time()` and `idmef_time_set_from_time()`
- `idmef_time_new_from_string()` and `idmef_time_set_from_string()`

## Details

### idmef_time_t

    typedef struct idmef_time idmef_time_t;

### idmef_time_ref ()

    idmef_time_t *      idmef_time_ref                      (idmef_time_t *time);

Increases `time` reference count. `idmef_time_destroy()` won't destroy `time` until the refcount reach 0.

`time` : | Pointer to an idmef_time_t object.
Returns : | The `time` provided argument.

### idmef_time_new ()

    int                 idmef_time_new                      (idmef_time_t **time);

Creates an empty idmef_time_t object and store it in `time`.

`time` : | Address where to store the created idmef_time_t object.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_new_from_time ()

    int                 idmef_time_new_from_time            (idmef_time_t **time,
                                                             const time_t *t);

Creates a new idmef_time_t object and store it in `time`. This object will be filled with information available in `t`. The created `time` won't contain micro seconds information, since theses are not available within `t`.

`time` : | Address where to store the created idmef_time_t object.
`t` : | Pointer to a time_t.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_new_from_gettimeofday ()

    int                 idmef_time_new_from_gettimeofday    (idmef_time_t **time);

Creates an idmef_time_t object filled with information retrieved using `gettimeofday()`, and stores it in `time`.

`time` : | Address where to store the created idmef_time_t object.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_new_from_string ()

    int                 idmef_time_new_from_string          (idmef_time_t **time,
                                                             const char *buf);

Creates an idmef_time_t object filled with information retrieved from the user provided `buf`, containing a string describing a time in a format conforming to the IDMEF definition (v. 0.10, section 3.2.6).

Additionally, the provided time might be separated with white spaces, instead of the IDMEF define 'T' character. The format might not specify a timezone (will assume UTC in this case).

The resulting idmef_time_t object is stored in `time`.

`time` : | Address where to store the created idmef_time_t object.
`buf` : | Pointer to a string describing a time in an IDMEF conforming format.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_new_from_ntpstamp ()

    int                 idmef_time_new_from_ntpstamp        (idmef_time_t **time,
                                                             const char *buf);

Creates an idmef_time_t object filled with information provided from the `buf` NTP timestamp, and stores it in `time`.

`time` : | Address where to store the created idmef_time_t object.
`buf` : | Pointer to a string containing an NTP timestamp.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_new_from_timeval ()

    int                 idmef_time_new_from_timeval         (idmef_time_t **time,
                                                             const struct timeval *tv);

Creates an idmef_time_t object filled with information provided within the `tv` structure.

`time` : | Address where to store the created idmef_time_t object.
`tv` : | Pointer to a struct timeval (see `gettimeofday()`).
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_set_from_time ()

    void                idmef_time_set_from_time            (idmef_time_t *time,
                                                             const time_t *t);

Fills `time` from the information described by `t`. `time` won't contain micro seconds information, since theses are not available within `t`.

`time` : | Pointer to an idmef_time_t object.
`t` : | Pointer to a time_t.

### idmef_time_set_from_gettimeofday ()

    int                 idmef_time_set_from_gettimeofday    (idmef_time_t *time);

Fills `time` with information retrieved using `gettimeofday()`.

`time` : | Pointer to an idmef_time_t object.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_set_from_string ()

    int                 idmef_time_set_from_string          (idmef_time_t *time,
                                                             const char *buf);

Fills `time` object with information retrieved from the user provided `buf`, containing a string describing a time in a format conforming to the IDMEF definition (v. 0.10, section 3.2.6).

Additionally, the provided time might be separated with white spaces, instead of the IDMEF defined 'T' character.

If there is no UTC offset specified, we assume that the provided time is local, and compute the GMT offset by ourselve.

`time` : | Pointer to an idmef_time_t object.
`buf` : | Pointer to a string describing a time in an IDMEF conforming format.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_set_from_ntpstamp ()

    int                 idmef_time_set_from_ntpstamp        (idmef_time_t *time,
                                                             const char *buf);

Fills the `time` object with information provided within the `buf` NTP timestamp.

`time` : | Pointer to a idmef_time_t object.
`buf` : | Pointer to a string containing an NTP timestamp.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_set_from_timeval ()

    int                 idmef_time_set_from_timeval         (idmef_time_t *time,
                                                             const struct timeval *tv);

Fills `time` object filled with information provided within the `tv` structure.

`time` : | Pointer to an idmef_time_t object.
`tv` : | Pointer to a struct timeval (see `gettimeofday()`).
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_destroy_internal ()

    void                idmef_time_destroy_internal         (idmef_time_t *time);

`time` : |

### idmef_time_destroy ()

    void                idmef_time_destroy                  (idmef_time_t *time);

Destroys `time` if refcount reach 0.

`time` : | Pointer to an idmef_time_t object.

### idmef_time_clone ()

    int                 idmef_time_clone                    (const idmef_time_t *src,
                                                             idmef_time_t **dst);

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

`src` : | Pointer to a idmef_time_t to clone.
`dst` : | Address where to store the cloned `src` object.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_copy ()

    int                 idmef_time_copy                     (const idmef_time_t *src,
                                                             idmef_time_t *dst);

Copies `src` internal to `dst`.

`src` : | Pointer to a idmef_time_t to copy data from.
`dst` : | Pointer to a idmef_time_t to copy data to.
Returns : | 0 on success, a negative value if an error occured.

### idmef_time_set_sec ()

    void                idmef_time_set_sec                  (idmef_time_t *time,
                                                             uint32_t sec);

Sets the number of second from the Epoch to `sec` within `time`.

WARNING: this is just an accessor function, and using it to set `time` current time also requires the use of `idmef_time_set_usec()` and `idmef_time_set_gmt_offset()`.

`time` : | Pointer to a idmef_time_t.
`sec` : | Number of seconds since the Epoch.

### idmef_time_set_usec ()

    void                idmef_time_set_usec                 (idmef_time_t *time,
                                                             uint32_t usec);

Sets the number of micro second to `usec` within `time`.

WARNING: this is just an accessor function, and using it to set `time` current time also requires the use of `idmef_time_set_sec()` and `idmef_time_set_gmt_offset()`.

`time` : | Pointer to a idmef_time_t.
`usec` : | Number of micro seconds to set within `time`.

### idmef_time_set_gmt_offset ()

    void                idmef_time_set_gmt_offset           (idmef_time_t *time,
                                                             int32_t gmtoff);

Sets the GMT offset `gmtoff`, in seconds, within `time`.

WARNING: this is just an accessor function, and using it to set `time` current time also requires the use of `idmef_time_set_sec()` and `idmef_time_set_usec()`.

`time` : | Pointer to a idmef_time_t.
`gmtoff` : | GMT offset for `time`, in seconds.

### idmef_time_get_sec ()

    uint32_t            idmef_time_get_sec                  (const idmef_time_t *time);

Returns the number of second since the Epoch (00:00:00 UTC, January 1, 1970), previously set within `time`.

`time` : | Pointer to a idmef_time_t.
Returns : | The number of seconds.

### idmef_time_get_usec ()

    uint32_t            idmef_time_get_usec                 (const idmef_time_t *time);

Returns the u-second member of `time`.

`time` : | Pointer to a idmef_time_t.
Returns : | The number of u-seconds.

### idmef_time_get_gmt_offset ()

    int32_t             idmef_time_get_gmt_offset           (const idmef_time_t *time);

Returns the GMT offset that applies to `time`.

`time` : | Pointer to a idmef_time_t.
Returns : | The GMT offset, in seconds.

### idmef_time_to_string ()

    int                 idmef_time_to_string                (const idmef_time_t *time,
                                                             prelude_string_t *out);

Translates `time` to an user readable string conforming to the IDMEF defined time format.

`time` : | Pointer to an IDMEF time structure.
`out` : | Pointer to a prelude_string_t output buffer.
Returns : | number of bytes written on success, a negative value if an error occured.

### idmef_time_to_ntpstamp ()

    int                 idmef_time_to_ntpstamp              (const idmef_time_t *time,
                                                             prelude_string_t *out);

Translates `time` to an user readable NTP timestamp string, conforming to the IDMEF defined time format.

`time` : | Pointer to an IDMEF time structure.
`out` : | Pointer to a prelude_string_t output buffer.
Returns : | number of bytes written on success, a negative value if an error occured.