writer.h File Reference

Fixbuf message writer interface. More...

#include <fixbuf/autoinc.h>
#include <fixbuf/template.h>

Go to the source code of this file.

Defines

#define FIX_WMSG_SZ 65536

Maximum message size; also defines the size of the internal FixWriter message buffer.

#define FIX_TID_DEFAULT 0

Pass as d_tid parameter to fix_write() to use the FixWriter's current set template ID as the destination template ID.

Typedefs

typedef _FixWriter FixWriter

Opaque FixWriter data structure.

typedef gboolean(* FixWriterMgtFn )(void *ectx, void **ictx, GError **err)

FixWriter low-level output management function.

typedef gboolean(* FixWriteFn )(void *ectx, void *ictx, uint8_t *buf, uint32_t len, GError **err)

FixWriter low-level output function.

Functions

FixWriter * fix_writer_alloc (FixIERegistry *ier, FixWriterMgtFn msgstart, FixWriteFn write, FixWriterMgtFn msgend)

Allocate a new FixWriter.

void fix_write_start (FixWriter *wmsg, void *ectx, uint32_t export_time, uint32_t sequence, uint32_t source, uint16_t mtu)

Start writing an IPFIX message with the given header information to an output stream.

gboolean fix_writer_final_set (FixWriter *wmsg, uint16_t tid, GError **err)

Declare a final set on an IPFIX message.

gboolean fix_write_template (FixWriter *wmsg, uint16_t tid, GError **err)

Write a single previously allocated and activated template to an IPFIX message.

gboolean fix_write_templates (FixWriter *wmsg, GError **err)

Write every available currently active, non-private template to an IPFIX message, automatically restarting the message if it is full.

gboolean fix_writer_revoke_template (FixWriter *wmsg, uint16_t tid, GError **err)

Revoke a template by writing a template revocation and removing the template from the session.

gboolean fix_write (FixWriter *wmsg, uint16_t s_tid, uint16_t d_tid, uint8_t *recbase, uint32_t recsize, GError **err)

Write a record to an IPFIX message with transcoding as appropriate.

gboolean fix_write_autobounce (FixWriter *wmsg, uint16_t s_tid, uint16_t d_tid, uint8_t *recbase, uint32_t recsize, GError **err)

Write a record to an IPFIX message, automatically restarting the message if it is full.

gboolean fix_write_end (FixWriter *wmsg, GError **err)

Finish writing a message on a FixWriter.

gboolean fix_writer_active (FixWriter *wmsg)

Determine a writer's active state.

void fix_writer_free (FixWriter *wmsg)

Dispose of a FixWriter.

void fix_writer_dump_stats (FixWriter *wmsg)

Dump writer statistics to standard error.

gboolean fix_write_fp (void *ectx, void *ictx, uint8_t *buf, uint32_t len, GError **err)

Low-level output write function for FILE output.

gboolean fix_write_fd (void *ectx, void *ictx, uint8_t *buf, uint32_t len, GError **err)

Low-level output write function for file descriptor output.

Detailed Description

Fixbuf message writer interface.

A FixWriter is a reusable IPFIX message writer object bound to a fixbuf session context for writing to a specific type of low-level output stream. This interface supplies two low-level output stream interfaces, one to a GIOChannel and one to an ANSI C file pointer.

Typedef Documentation

typedef gboolean(* FixWriteFn)(void *ectx, void *ictx, uint8_t *buf, uint32_t len, GError **err)

FixWriter low-level output function.
This type points to the required low-level message data write function passed to fix_writer_alloc().

typedef gboolean(* FixWriterMgtFn)(void *ectx, void **ictx, GError **err)

FixWriter low-level output management function.
This type points to the optional low-level message start and low-level message end functions passed to fix_writer_alloc().

Function Documentation

gboolean fix_write ( FixWriter * wmsg,

uint16_t s_tid,

uint16_t d_tid,

uint8_t * recbase,

uint32_t recsize,

GError ** err

)

Write a record to an IPFIX message with transcoding as appropriate.
If the source template contains any variable length information elements, they must be represented in the record by FixVarlen structures.

Parameters:

wmsg FixWriter to write record to

s_tid template ID describing record at recbase.

d_tid template ID of record to write.

recbase pointer to start of record.

recsize number of bytes to write.

err an error description

Returns:
TRUE on success, FALSE (and set *err) otherwise

gboolean fix_write_autobounce ( FixWriter * wmsg,

uint16_t s_tid,

uint16_t d_tid,

uint8_t * recbase,

uint32_t recsize,

GError ** err

)

Write a record to an IPFIX message, automatically restarting the message if it is full.
Designed to allow applications to leave message boundaries to the library. Transcodes message as appropriate. If the source template contains any variable length information elements, they must be represented in the record by FixVarlen structures.
If autobounce causes a new message to be started, that message will have identical mtu, source, and export time, and its sequence number will be incremented by one. The export time behavior is probably not what you want; this will be fixed in a future release of fixbuf.

Parameters:

wmsg FixWriter to write record to

s_tid template ID describing record at recbase.

d_tid template ID of record to write.

recbase pointer to start of record.

recsize number of bytes to write.

err an error description

Returns:
TRUE on ultimate success, FALSE (and set *err) otherwise

gboolean fix_write_end ( FixWriter * wmsg,

GError ** err

)

Finish writing a message on a FixWriter.
Flushes the internal buffer to low-level output, and resets the FixWriter for reuse by a subsequent fix_write_start() call.

Parameters:

wmsg FixWriter to finish

err an error description

Returns:
TRUE on success, FALSE (and set *err) otherwise

gboolean fix_write_fd ( void * ectx,

void * ictx,

uint8_t * buf,

uint32_t len,

GError ** err

)

Low-level output write function for file descriptor output.
ectx is assumed to be a file descriptor or socket, opened for writing . Does not require message start or end functions. Pass this to fix_writer_alloc().

Parameters:

ectx external context from fix_write_start(); a file descriptor.

ictx internal context; ignored.

buf buffer to write

len length of buffer

err an error description

Returns:
TRUE on success, FALSE otherwise.

gboolean fix_write_fp ( void * ectx,

void * ictx,

uint8_t * buf,

uint32_t len,

GError ** err

)

Low-level output write function for FILE output.
ectx is assumed to be a pointer to a FILE, opened for writing . Does not require message start or end functions. Pass this to fix_writer_alloc().

Parameters:

ectx external context from fix_write_start(); a FILE *.

ictx internal context; ignored.

buf buffer to write

len length of buffer

err an error description

Returns:
TRUE on success, FALSE otherwise.

void fix_write_start ( FixWriter * wmsg,

void * ectx,

uint32_t export_time,

uint32_t sequence,

uint32_t source,

uint16_t mtu

)

Start writing an IPFIX message with the given header information to an output stream.
This passes a new stream external context to the low-level output and writes a valid IPFIX message header into the FixWriter's internal buffer.

Parameters:

wmsg Writer to begin writing to

ectx Stream external context. Passed as ectx to the low-level message start, write, and end functions, this should point to a data structure of the type expected by the low-level output routines. For the supplied fix_write_iochannel(), this is a GIOChannel *. For the supplied fix_write_fp(), this is a FILE *.

export_time Message export time in epoch seconds

sequence Message sequence number

source Message source ID

mtu Message MTU in octets. The message will not be permitted to grow any larger than this size. Use 0 to create a final message (that is, a message that will use the mechanism in draft-trammell-ipfix-file-00 for efficient persistent storage; note that this is ONLY useful for file-based low-level output)

gboolean fix_write_template ( FixWriter * wmsg,

uint16_t tid,

GError ** err

)

Write a single previously allocated and activated template to an IPFIX message.
Does not honor the template private flag; this may be used to write private templates to an IPFIX message.

Parameters:

wmsg FixWriter to write template to

tid Template ID of template to write.

err an error description

Returns:
TRUE on success, FALSE (and set *err) otherwise

gboolean fix_write_templates ( FixWriter * wmsg,

GError ** err

)

Write every available currently active, non-private template to an IPFIX message, automatically restarting the message if it is full.

Parameters:

wmsg FixWriter to write template to

err an error description

Returns:
TRUE on success, FALSE (and set *err) otherwise

gboolean fix_writer_active ( FixWriter * wmsg )

Determine a writer's active state.
A writer is active if it is presently writing to an IPFIX message; that is, between calls to fix_write_start() and fix_write_end().

Parameters:

wmsg FixWriter to get active state for

Returns:
the FixWriter's active state.

FixWriter* fix_writer_alloc ( FixIERegistry * ier,

FixWriterMgtFn msgstart,

FixWriteFn write,

FixWriterMgtFn msgend

)

Allocate a new FixWriter.
Creates a new writer using supplied message start, write, and end functions as low-level output, which will use a given IE registry for information element definitions. Since FixWriters are reusable and reasonably expensive to allocate, applications should only allocate one writer per simultaneously open output stream.

Parameters:

ier FixIERegistry to use for information element definitions

msgstart low-level output start function called by fix_write_start() before writing the IPFIX Message header. Use this function to prepare the low-level output stream or allocate any internal per-message state required by the low-level write function. Optional; pass NULL if not required.

write low-level output write function called to write IPFIX Message octets to the output stream.

msgend low-level output end function called by fix_write_end() after flushing the FixWriter internal buffer to the output stream using the low-level write function. Use this function to flush the low-level output stream or clean up any internal per-message state required by the low-level write function. Optional; pass NULL if not required.

Returns:
a new FixWriter

void fix_writer_dump_stats ( FixWriter * wmsg )

Dump writer statistics to standard error.

Parameters:

wmsg FixWriter to dump.

gboolean fix_writer_final_set ( FixWriter * wmsg,

uint16_t tid,

GError ** err

)

Declare a final set on an IPFIX message.
Starts a new data set for the given TID and writes it as a final set; that is, a set that persists to end of file. Only available on started messages with an MTU of 0.

Parameters:

wmsg Writer to declare a final set on

tid Template ID of the final set

err an error description

Returns:
TRUE on success, FALSE (and set *err) otherwise

void fix_writer_free ( FixWriter * wmsg )

Dispose of a FixWriter.

Parameters:

wmsg FixWriter to free.

gboolean fix_writer_revoke_template ( FixWriter * wmsg,

uint16_t tid,

GError ** err

)

Revoke a template by writing a template revocation and removing the template from the session.

Parameters:

wmsg FixWriter to write revocation to

tid Template ID of template to write.

err an error description

Returns:
TRUE on success, FALSE (and set *err) otherwise


Defines
#define	FIX_WMSG_SZ 65536
	Maximum message size; also defines the size of the internal FixWriter message buffer.
#define	FIX_TID_DEFAULT 0
	Pass as d_tid parameter to fix_write() to use the FixWriter's current set template ID as the destination template ID.
Typedefs
typedef _FixWriter	FixWriter
	Opaque FixWriter data structure.
typedef gboolean(*	FixWriterMgtFn )(void ectx, void ictx, GError *err)
	FixWriter low-level output management function.
typedef gboolean(*	FixWriteFn )(void ectx, void ictx, uint8_t buf, uint32_t len, GError *err)
	FixWriter low-level output function.
Functions
FixWriter *	fix_writer_alloc (FixIERegistry *ier, FixWriterMgtFn msgstart, FixWriteFn write, FixWriterMgtFn msgend)
	Allocate a new FixWriter.
void	fix_write_start (FixWriter wmsg, void ectx, uint32_t export_time, uint32_t sequence, uint32_t source, uint16_t mtu)
	Start writing an IPFIX message with the given header information to an output stream.
gboolean	fix_writer_final_set (FixWriter wmsg, uint16_t tid, GError *err)
	Declare a final set on an IPFIX message.
gboolean	fix_write_template (FixWriter wmsg, uint16_t tid, GError *err)
	Write a single previously allocated and activated template to an IPFIX message.
gboolean	fix_write_templates (FixWriter wmsg, GError *err)
	Write every available currently active, non-private template to an IPFIX message, automatically restarting the message if it is full.
gboolean	fix_writer_revoke_template (FixWriter wmsg, uint16_t tid, GError *err)
	Revoke a template by writing a template revocation and removing the template from the session.
gboolean	fix_write (FixWriter wmsg, uint16_t s_tid, uint16_t d_tid, uint8_t recbase, uint32_t recsize, GError **err)
	Write a record to an IPFIX message with transcoding as appropriate.
gboolean	fix_write_autobounce (FixWriter wmsg, uint16_t s_tid, uint16_t d_tid, uint8_t recbase, uint32_t recsize, GError **err)
	Write a record to an IPFIX message, automatically restarting the message if it is full.
gboolean	fix_write_end (FixWriter wmsg, GError *err)
	Finish writing a message on a FixWriter.
gboolean	fix_writer_active (FixWriter *wmsg)
	Determine a writer's active state.
void	fix_writer_free (FixWriter *wmsg)
	Dispose of a FixWriter.
void	fix_writer_dump_stats (FixWriter *wmsg)
	Dump writer statistics to standard error.
gboolean	fix_write_fp (void ectx, void ictx, uint8_t buf, uint32_t len, GError *err)
	Low-level output write function for FILE output.
gboolean	fix_write_fd (void ectx, void ictx, uint8_t buf, uint32_t len, GError *err)
	Low-level output write function for file descriptor output.