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

FixWriterfix_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


© 2005-2006 Carnegie Mellon University
Generated Thu Jul 6 16:00:08 2006 for libfixbuf 0.4.1 by Doxygen 1.4.5.