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.
Generated by GTK-Doc V1.11