template.h File Reference

Fixbuf template interface. More...

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

Go to the source code of this file.

Data Structures

struct  _FixTemplateCtx
 A template context; analogous to an IPFIX session. More...
struct  _FixTemplate
 A fixbuf template. More...
struct  _FixVarfield
 A variable-length field value. More...
struct  _FixTemplateSpec
 A template field specifier for use in programatically defining templates. More...

Defines

#define FIX_ERROR_DOMAIN   g_quark_from_string("fixbufError")
 All fixbuf error are returned within the FIX_ERROR_DOMAIN domain.
#define FIX_ERROR_NOTEMPLATE   1
 No template was available for the given template ID.
#define FIX_ERROR_EOF   2
 End of IPFIX message.
#define FIX_ERROR_SHORT   3
 Premature end of IPFIX message.
#define FIX_ERROR_IPFIX   4
 Illegal IPFIX mesaage content on read.
#define FIX_ERROR_BUFSZ   5
 An application-supplied record buffer was too small.
#define FIX_ERROR_IMPL   6
 The requested feature is not yet implemented.
#define FIX_ERROR_IO   7
 An I/O error occured.
#define FIX_ERROR_NOLOWDATA   8
 No data is available for reading from the low-level I/O layer.
#define FIX_TID_TS   2
 Template Set template ID.
#define FIX_TID_OTS   3
 Options Template Set template ID.
#define FIX_TID_XTS   4
 Extended Template Set template ID.
#define FIX_TID_MIN   256
 Minimum user template ID.
#define FIX_TID_AUTO   0
 Assign a template ID automatically.
#define FIX_END_TEMPLATE_SPEC   { NULL, 0, 0, NULL }
 Convenience element for NULL-terminating a FixTemplateSpec array.

Typedefs

typedef _FixTemplateCtx FixTemplateCtx
 A template context; analogous to an IPFIX session.
typedef _FixTemplate FixTemplate
 A fixbuf template.
typedef _FixVarfield FixVarfield
 A variable-length field value.
typedef _FixTemplateSpec FixTemplateSpec
 A template field specifier for use in programatically defining templates.

Functions

FixTemplatefix_template_alloc (FixTemplateCtx *tctx, uint16_t tid)
 Allocate a new template with a given ID for a given role within a given session context.
void fix_template_add_ie (FixTemplate *tmpl, FixIEKey *iek, uint16_t len_override, uint32_t flags_override)
 Add an information element to an inactive template.
void fix_template_add_spec (FixTemplate *tmpl, FixTemplateSpec *spec)
 Add a single information element from a FixTemplateSpec.
void fix_template_add_spec_ary (FixTemplate *tmpl, FixTemplateSpec *spec)
 Add information elements from a zero-terminated FixTemplateSpec array.
void fix_template_opt_scope (FixTemplate *tmpl, uint16_t scope)
 Modify an inactive template's scope information element count.
void fix_template_privatize (FixTemplate *tmpl)
 Privatize an inactive template.
void fix_template_activate (FixTemplate *tmpl)
 Activate an inactive template.
FixTemplatefix_template_lookup (FixTemplateCtx *tctx, uint16_t tid, GError **err)
 Look up a template given a template ID and a role.
void fix_template_free (FixTemplate *tmpl)
 Free a template.
void fix_template_revoke (FixTemplate *tmpl)
 Revoke a template.


Detailed Description

Fixbuf template interface.

Defines the template datatype and public API, and the libfixbuf error domain. All fixbuf applications must include this header.


Define Documentation

#define FIX_ERROR_BUFSZ   5
 

An application-supplied record buffer was too small.

May occur at runtime if the input stream contains records with variable-length records much larger than expected.

#define FIX_ERROR_EOF   2
 

End of IPFIX message.

Either there are no more records present in the message on read, or the message MTU has been reached on write. In the latter case, the application must explicitly end the message and start a new one before writing can continue.

#define FIX_ERROR_IMPL   6
 

The requested feature is not yet implemented.

Presently returned in two situations: when attempting to read a final set defined by a template containing variable length information elements; and when attempting to transcode a fixed-length information element into a variable-length information element, or vice-versa.

#define FIX_ERROR_IPFIX   4
 

Illegal IPFIX mesaage content on read.

The input stream is malformed, or is not an IPFIX Message after all.

#define FIX_ERROR_NOLOWDATA   8
 

No data is available for reading from the low-level I/O layer.

This may occur when using a blocking low-level I/O layer (e.g. the UDP interface in udp.c) and a read call times out (EWOULDBLOCK) or is interrupted (EINTR).

#define FIX_ERROR_SHORT   3
 

Premature end of IPFIX message.

The reader ran out of bytes in the middle of a record. The input stream is malformed.


Typedef Documentation

typedef struct _FixTemplate FixTemplate
 

A fixbuf template.

Public access is provided as a convenience; applications should use the fixbuf API to manipulate the fields of this structure when possible.

typedef struct _FixTemplateCtx FixTemplateCtx
 

A template context; analogous to an IPFIX session.

Both FixReader and FixWriter contain this structure as their first member, so they may be freely cast to FixTemplateCtx where necessary.

typedef struct _FixTemplateSpec FixTemplateSpec
 

A template field specifier for use in programatically defining templates.

Pass an array of these to looks up registered information elements by name with optional length and flags overrides.

typedef struct _FixVarfield FixVarfield
 

A variable-length field value.

Used by fix_read() and fix_write() (the non-raw, transcoding interfaces) to represent variable-length information element content.


Function Documentation

void fix_template_activate FixTemplate tmpl  ) 
 

Activate an inactive template.

Causes a template to no longer be mutable, and computes internal fields derived from information element array. Only active templates can be used to read and write IPFIX data.

Parameters:
tmpl template to activate

void fix_template_add_ie FixTemplate tmpl,
FixIEKey iek,
uint16_t  len_override,
uint32_t  flags_override
 

Add an information element to an inactive template.

Will look up length and flags in the IE registry.

Parameters:
tmpl the template to add to.
iek information element key (enterprise and number) to add
len_override if non-zero, override length with this value.
flags_override if non-zero, override flags with this value.

void fix_template_add_spec FixTemplate tmpl,
FixTemplateSpec spec
 

Add a single information element from a FixTemplateSpec.

Use this to programmatically define templates.

Parameters:
tmpl template to add to.
spec pointer to template spec.

void fix_template_add_spec_ary FixTemplate tmpl,
FixTemplateSpec spec
 

Add information elements from a zero-terminated FixTemplateSpec array.

Use this to programmatically define templates.

Parameters:
tmpl template to add to.
spec pointer to first element in template spec array

FixTemplate* fix_template_alloc FixTemplateCtx tctx,
uint16_t  tid
 

Allocate a new template with a given ID for a given role within a given session context.

Automatically inserts the template into the session's template table(s) appropriate for the role. If the given template ID is FIX_TID_AUTO, assigns a valid template ID automatically.

Parameters:
tctx template context; may be cast from a FixReader or FixReader
tid template ID to assign, or FIX_TID_AUTO for automatic template ID
Returns:
a new, empty, inactive template.

void fix_template_free FixTemplate tmpl  ) 
 

Free a template.

Used internally by the session template tables; applications MUST not call this as it will cause the session template tables to refer to a destroyed template. Free templates instead either by replacing them in the session template tables, by revoking them via a FixReader of FixWriter, or by destroying the enclosing session context.

Parameters:
tmpl template to free

FixTemplate* fix_template_lookup FixTemplateCtx tctx,
uint16_t  tid,
GError **  err
 

Look up a template given a template ID and a role.

Returns the requested template, or NULL if the no template exists in the given template context for the given template ID. Used internally by FixReader and FixWriter to find templates for transcoding purposes.

Parameters:
tctx template context; may be cast from a FixReader or FixReader
tid template ID to look up
err an error description
Returns:
the requested template, if available.

void fix_template_opt_scope FixTemplate tmpl,
uint16_t  scope
 

Modify an inactive template's scope information element count.

Nonzero scope counts will cause a template to become an IPFIX Options Template. By default, newly allocated templates have a zero scope count, making them standard IPFIX Templates.

Parameters:
tmpl template to modify scope count of
scope new scope count

void fix_template_privatize FixTemplate tmpl  ) 
 

Privatize an inactive template.

Causes a template to not be exported by fix_write_templates(). Use this for templates describing internal data structures (with padding for alignment, containing fields not intended for export, etc.). Privatization has no effect on read templates.

Parameters:
tmpl template to privatize

void fix_template_revoke FixTemplate tmpl  ) 
 

Revoke a template.

Used internally by FixReader and FixWriter to handle template revocation.

Parameters:
tmpl template to revoke


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