reader.h File Reference

Fixbuf message reader interface. More...

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

Go to the source code of this file.

Defines

#define FIX_RMSG_SZ   65536
 Maximum message size; also defines the size of the internal FixReader message buffer.

Typedefs

typedef _FixReader FixReader
 Opaque FixReader data structure.
typedef gboolean(* FixReaderMgtFn )(void *ectx, void **ictx, GError **err)
 FixReader low-level input management function.
typedef gboolean(* FixReadFn )(void *ectx, void *ictx, uint8_t *buf, uint32_t *len, GError **err)
 FixReader low-level input function.

Functions

FixReaderfix_reader_alloc (FixIERegistry *ier, FixReaderMgtFn msgstart, FixReadFn msgread, FixReaderMgtFn msgend)
 Allocate a new FixReader.
gboolean fix_read_start (FixReader *rmsg, void *ectx, GError **err)
 Start reading an IPFIX message with the given header information from an input stream.
gboolean fix_read (FixReader *rmsg, uint16_t tid, uint8_t *buf, uint32_t *d_len, GError **err)
 Read the next data record from an IPFIX message with transcoding as appropriate.
gboolean fix_read_autobounce (FixReader *rmsg, uint16_t d_tid, uint8_t *buf, uint32_t *d_len, GError **err)
 Read the next data record from an IPFIX message with transcoding as appropriate.
FixTemplatefix_reader_last_template (FixReader *rmsg)
 Get the native template for the last record read by fix_read() or fix_read_autobounce().
FixTemplatefix_reader_next_template (FixReader *rmsg, GError **err)
 Get the native template for the next record available from the IPFIX message.
uint32_t fix_read_export_time (FixReader *rmsg)
 Get the export time of the message from which records are currently being read.
void fix_read_end (FixReader *rmsg)
 Force a FixReader to stop reading its IPFIX message.
gboolean fix_reader_active (FixReader *rmsg)
 Determine a reader's active state.
void fix_reader_free (FixReader *rmsg)
 Dispose of a FixReader.
void fix_reader_dump_stats (FixReader *rmsg)
 Dump reader statistics to standard error.
gboolean fix_read_fp (void *ectx, void *ictx, uint8_t *buf, uint32_t *len, GError **err)
 Low-level input read function for FILE input.
gboolean fix_read_fd (void *ectx, void *ictx, uint8_t *buf, uint32_t *len, GError **err)
 Low-level input read function for file descriptors.


Detailed Description

Fixbuf message reader interface.

A FixReader is a reusable IPFIX message reader object bound to a fixbuf session context for reading 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(* FixReaderMgtFn)(void *ectx, void **ictx, GError **err)
 

FixReader low-level input management function.

This type points to the optional low-level message start and low-level message end functions passed to fix_reader_alloc().

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

FixReader low-level input function.

This type points to the required low-level message data read function passed to fix_reader_alloc().


Function Documentation

gboolean fix_read FixReader rmsg,
uint16_t  tid,
uint8_t *  buf,
uint32_t *  d_len,
GError **  err
 

Read the next data record from an IPFIX message with transcoding as appropriate.

Reads and stores any templates that may be in the message before the next record. If the destination template contains any variable length information elements, they will be stored in the record buffer as FixVarlen structures. These FixVarlen structures contain pointers directly into the reader's message buffer, so their contents must be copied out before the next call to fix_read().

Parameters:
rmsg Reader to read record from
tid Template ID to transcode read record to
buf Pointer to buffer to store record into
d_len Pointer to length of buffer; on input, defines buffer size, on output, defines size of read record.
err an error description
Returns:
TRUE on success, FALSE otherwise.

gboolean fix_read_autobounce FixReader rmsg,
uint16_t  d_tid,
uint8_t *  buf,
uint32_t *  d_len,
GError **  err
 

Read the next data record from an IPFIX message with transcoding as appropriate.

Attempts to read the next IPFIX message from the stream on EOF. Reads and stores any templates that may be in the message before the next record. If the destination template contains any variable length information elements, they will be stored in the record buffer as FixVarlen structures. These FixVarlen structures contain pointers directly into the reader's message buffer, so their contents must be copied out before the next call to fix_read().

Parameters:
rmsg Reader to read record from
d_tid Template ID to transcode read record to
buf Pointer to buffer to store record into
d_len Pointer to length of buffer; on input, defines buffer size, on output, defines size of read record.
err an error description
Returns:
TRUE on ultimate success, FALSE otherwise.

void fix_read_end FixReader rmsg  ) 
 

Force a FixReader to stop reading its IPFIX message.

Used internally by FixReader to clean up on end-of-file, this can also be used to force a FixReader to stop reading prematurely, for example, on non-read-related application error.

Parameters:
rmsg FixReader to end

uint32_t fix_read_export_time FixReader rmsg  ) 
 

Get the export time of the message from which records are currently being read.

Time is returned as seconds since the Unix epoch.

Parameters:
rmsg active message reader to get export time from.
Returns:
message export time, or 0 if the reader is inactive.

gboolean fix_read_fd void *  ectx,
void *  ictx,
uint8_t *  buf,
uint32_t *  len,
GError **  err
 

Low-level input read function for file descriptors.

ectx is assumed to be a file descriptor or socket, opened for reading. Does not require message start or end functions. Pass this to fix_reader_alloc().

Parameters:
ectx external context from fix_read_start(); a GIOChannel *.
ictx internal context; ignored.
buf buffer to read
len Pointer to length of buffer; on input, defines available buffer size, on output, defines size of read buffer.
err an error description
Returns:
TRUE on success, FALSE otherwise.

gboolean fix_read_fp void *  ectx,
void *  ictx,
uint8_t *  buf,
uint32_t *  len,
GError **  err
 

Low-level input read function for FILE input.

ectx is assumed to be a pointer to a FILE, opened for reading. Does not require message start or end functions. Pass this to fix_reader_alloc().

Parameters:
ectx external context from fix_read_start(); a GIOChannel *.
ictx internal context; ignored.
buf buffer to read
len Pointer to length of buffer; on input, defines available buffer size, on output, defines size of read buffer.
err an error description
Returns:
TRUE on success, FALSE otherwise.

gboolean fix_read_start FixReader rmsg,
void *  ectx,
GError **  err
 

Start reading an IPFIX message with the given header information from an input stream.

This passes a new stream external context to the low-level input and reads an IPFIX Message Header into the FixReader's internal buffer.

Parameters:
rmsg Reader to begin reading from.
ectx Stream external context. Passed as ectx to the low-level message start, read, and end functions, this should point to a data structure of the type expected by the low-level input routines. For the supplied fix_read_iochannel(), this is a GIOChannel *. For the supplied fix_read_fp(), this is a FILE *.
err an error description
Returns:
TRUE on success, FALSE otherwise.

gboolean fix_reader_active FixReader rmsg  ) 
 

Determine a reader's active state.

A reader is active if it is presently reading from an IPFIX message; that is, between the call to fix_read_start() and the EOF return from fix_read().

Parameters:
rmsg FixReader to get active state for
Returns:
the FixReader's active state

FixReader* fix_reader_alloc FixIERegistry ier,
FixReaderMgtFn  msgstart,
FixReadFn  msgread,
FixReaderMgtFn  msgend
 

Allocate a new FixReader.

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

Parameters:
ier FixIERegistry to use for information element definitions
msgstart low-level input start function called by fix_read_start() before reading the IPFIX Message header. Use this function to prepare the low-level input stream or allocate any internal per-message state required by the low-level read function. Optional; pass NULL if not required.
msgread low-level input read function called to read IPFIX Message octets from the input stream.
msgend low-level input end function called at end of message detect. Use this function to clean up any internal per-message state required by the low-level read function. Optional; pass NULL if not required.
Returns:
a new FixReader

void fix_reader_dump_stats FixReader rmsg  ) 
 

Dump reader statistics to standard error.

Parameters:
rmsg FixReader to dump.

void fix_reader_free FixReader rmsg  ) 
 

Dispose of a FixReader.

Parameters:
rmsg FixReader to free.

FixTemplate* fix_reader_last_template FixReader rmsg  ) 
 

Get the native template for the last record read by fix_read() or fix_read_autobounce().

Does not attempt to read from the IPFIX message, so cannot fail.

Parameters:
rmsg Reader to peek template from
Returns:
The native template of the last record read from the stream, or NULL if no record has yet been read.

FixTemplate* fix_reader_next_template FixReader rmsg,
GError **  err
 

Get the native template for the next record available from the IPFIX message.

Reads and stores any templates that may be in the message before the next record.

Parameters:
rmsg Reader to peek template from
err an error description
Returns:
The template describing the next record the message, or NULL on error.


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