public.h File Reference
fixbuf IPFIX protocol library public interface. More...
#include <fixbuf/autoinc.h>
Go to the source code of this file.
Data Structures | |
struct | fbVarfield_st |
A variable-length field value. More... | |
struct | fbInfoElement_st |
A single IPFIX Information Element definition. More... | |
struct | fbInfoElementSpec_st |
A single IPFIX Information Element specification. More... | |
struct | fbConnSpec_st |
Connection specifier. More... | |
Defines | |
#define | FB_ERROR_DOMAIN g_quark_from_string("fixbufError") |
All fixbuf errors are returned within the FB_ERROR_DOMAIN domain. | |
#define | FB_ERROR_TMPL 1 |
No template was available for the given template ID. | |
#define | FB_ERROR_EOM 2 |
End of IPFIX message. | |
#define | FB_ERROR_EOF 3 |
End of IPFIX Message stream. | |
#define | FB_ERROR_IPFIX 4 |
Illegal IPFIX mesaage content on read. | |
#define | FB_ERROR_BUFSZ 5 |
A message was received larger than the collector buffer size. | |
#define | FB_ERROR_IMPL 6 |
The requested feature is not yet implemented. | |
#define | FB_ERROR_IO 7 |
An unspecified I/O error occured. | |
#define | FB_ERROR_NLREAD 8 |
No data is available for reading from the transport layer. | |
#define | FB_ERROR_NLWRITE 9 |
An attempt to write data to the transport layer failed due to closure of the remote end of the connection. | |
#define | FB_ERROR_NOELEMENT 10 |
The specified Information Element does not exist in the Information Model. | |
#define | FB_ERROR_CONN 11 |
A connection or association could not be established or maintained. | |
#define | FB_ERROR_NETFLOWV9 12 |
Illegal NetflowV9 content on a read. | |
#define | FB_ERROR_TRANSMISC 13 |
Miscellaneous error occured during translator operation. | |
#define | FB_IE_INIT(_name_, _ent_, _num_, _len_, _flags_) { {.name = _name_}, 0, _ent_, _num_, _len_, _flags_ } |
Convenience macro for creating fbInfoElement_t static initializers. | |
#define | FB_IE_NULL { {.name = NULL}, 0, 0, 0, 0, 0 } |
Convenience macro defining a null information element initializer to terminate a constant information element array for passing to fbInfoModelAddElementArray(). | |
#define | FB_IE_F_NONE 0x00000000 |
Default treatment flags value. | |
#define | FB_IE_F_ENDIAN 0x00000001 |
Information element endian conversion flag. | |
#define | FB_IE_F_REVERSIBLE 0x00000040 |
Information element reversible flag. | |
#define | FB_IE_F_ALIEN 0x00000080 |
Information element alien flag. | |
#define | FB_IE_VARLEN 65535 |
Information element length constant for variable-length IE. | |
#define | FB_IE_PEN_REVERSE 29305 |
Private enterprise number for reverse information elements (see draft-ietf-ipfix-biflow-03 section 6.1). | |
#define | FB_IE_VENDOR_BIT_REVERSE 0x4000 |
Reverse information element bit for vendor-specific information elements (see draft-ietf-ipfix-biflow-03 section 6.2). | |
#define | FB_IE_REVERSE_STR "reverse" |
Reverse information element name prefix. | |
#define | FB_IE_REVERSE_STRLEN 7 |
Length of reverse information element name prefix. | |
#define | FB_TID_AUTO 0 |
Template ID argument to pass to fbSessionAddTemplate to automatically assign a template ID. | |
#define | FB_TID_TS 2 |
Reserved set ID for template sets. | |
#define | FB_TID_OTS 3 |
Reserved set ID for options template sets. | |
#define | FB_TID_MIN_DATA 256 |
Minimum non-reserved template ID available for data sets. | |
#define | FB_IESPEC_NULL { NULL, 0, 0 } |
Convenience macro defining a null information element specification initializer to terminate a constant information element specifier array for passing to fbTemplateAppendSpecArray(). | |
#define | FB_CONNSPEC_INIT |
Convenience macro defining a null static fbConnSpec_t. | |
Typedefs | |
typedef struct fBuf_st | fBuf_t |
An IPFIX message buffer. | |
typedef struct fbVarfield_st | fbVarfield_t |
typedef struct fbInfoModel_st | fbInfoModel_t |
An IPFIX information model. | |
typedef struct fbInfoElement_st | fbInfoElement_t |
typedef struct fbTemplate_st | fbTemplate_t |
An IPFIX Template or Options Template. | |
typedef struct fbInfoElementSpec_st | fbInfoElementSpec_t |
typedef struct fbSession_st | fbSession_t |
An IPFIX Transport Session state container. | |
typedef enum fbTransport_en | fbTransport_t |
typedef struct fbConnSpec_st | fbConnSpec_t |
typedef struct fbExporter_st | fbExporter_t |
IPFIX Exporting Process endpoint. | |
typedef struct fbCollector_st | fbCollector_t |
IPFIX Collecting Process endpoint. | |
typedef struct fbListener_st | fbListener_t |
IPFIX Collecting Process session listener. | |
typedef gboolean(* | fbListenerAppInit_fn )(fbListener_t *listener, void **ctx, int fd, struct sockaddr *peer, size_t peerlen, GError **err) |
Application context initialization function type for fbListener_t. | |
typedef void(* | fbListenerAppFree_fn )(void *ctx) |
Application context free function type for fbListener_t. | |
Enumerations | |
enum | fbTransport_en { FB_SCTP, FB_TCP, FB_UDP, FB_DTLS_SCTP, FB_TLS_TCP, FB_DTLS_UDP } |
Transport protocol for connection specifier. More... | |
Functions | |
gboolean | fBufSetInternalTemplate (fBuf_t *fbuf, uint16_t int_tid, GError **err) |
Set the internal template on a buffer to the given template ID. | |
gboolean | fBufSetExportTemplate (fBuf_t *fbuf, uint16_t ext_tid, GError **err) |
Set the external template for export on a buffer to the given template ID. | |
void | fBufSetAutomaticMode (fBuf_t *fbuf, gboolean automatic) |
Set the automatic mode flag on a buffer. | |
fbSession_t * | fBufGetSession (fBuf_t *fbuf) |
Retrieve the session associated with a buffer. | |
void | fBufFree (fBuf_t *fbuf) |
Free a buffer. | |
fBuf_t * | fBufAllocForExport (fbSession_t *session, fbExporter_t *exporter) |
Allocate a new buffer for export. | |
fbExporter_t * | fBufGetExporter (fBuf_t *fbuf) |
Retrieve the exporting process endpoint associated with a buffer. | |
void | fBufSetExporter (fBuf_t *fbuf, fbExporter_t *exporter) |
Associate an exporting process endpoint with a buffer. | |
gboolean | fBufAppend (fBuf_t *fbuf, uint8_t *recbase, size_t recsize, GError **err) |
Append a record to a buffer. | |
gboolean | fBufEmit (fBuf_t *fbuf, GError **err) |
Emit the message currently in a buffer using the associated exporting process endpoint. | |
void | fBufSetExportTime (fBuf_t *fbuf, uint32_t extime) |
Set the export time on the message currently in a buffer. | |
fBuf_t * | fBufAllocForCollection (fbSession_t *session, fbCollector_t *collector) |
Allocate a new buffer for collection. | |
fbCollector_t * | fBufGetCollector (fBuf_t *fbuf) |
Retrieve the collecting process endpoint associated with a buffer. | |
void | fBufSetCollector (fBuf_t *fbuf, fbCollector_t *collector) |
Associate an collecting process endpoint with a buffer. | |
gboolean | fBufNext (fBuf_t *fbuf, uint8_t *recbase, size_t *recsize, GError **err) |
Retrieve a record from a buffer. | |
gboolean | fBufNextMessage (fBuf_t *fbuf, GError **err) |
Read a new message into a buffer using the associated collecting process endpoint. | |
uint32_t | fBufGetExportTime (fBuf_t *fbuf) |
Retrieve the export time on the message currently in a buffer. | |
fbTemplate_t * | fBufGetCollectionTemplate (fBuf_t *fbuf, uint16_t *ext_tid) |
Retrieve the external template used to read the last record from the buffer. | |
fbTemplate_t * | fBufNextCollectionTemplate (fBuf_t *fbuf, uint16_t *ext_tid, GError **err) |
Retrieve the external template that will be used to read the next record from the buffer. | |
fbInfoModel_t * | fbInfoModelAlloc () |
Allocate a new information model. | |
void | fbInfoModelFree (fbInfoModel_t *model) |
Free an information model. | |
void | fbInfoModelAddElement (fbInfoModel_t *model, fbInfoElement_t *ie) |
Add a single information element to an information model. | |
void | fbInfoModelAddElementArray (fbInfoModel_t *model, fbInfoElement_t *ie) |
Add multiple information elements in an array to an information model. | |
const fbInfoElement_t * | fbInfoModelGetElementByName (fbInfoModel_t *model, const char *name) |
Return a pointer to the canonical information element within an information model given the information element name. | |
fbTemplate_t * | fbTemplateAlloc (fbInfoModel_t *model) |
Allocate a new empty template. | |
gboolean | fbTemplateAppend (fbTemplate_t *tmpl, fbInfoElement_t *ex_ie, GError **err) |
Append an information element to a template. | |
gboolean | fbTemplateAppendSpec (fbTemplate_t *tmpl, fbInfoElementSpec_t *spec, uint32_t flags, GError **err) |
Append an information element described by specifier to a template. | |
gboolean | fbTemplateAppendSpecArray (fbTemplate_t *tmpl, fbInfoElementSpec_t *spec, uint32_t flags, GError **err) |
Append information elements described by a specifier array to a template. | |
uint32_t | fbTemplateCountElements (fbTemplate_t *tmpl) |
Determine number of information elements in a template. | |
void | fbTemplateSetOptionsScope (fbTemplate_t *tmpl, uint16_t scope_count) |
Set the number of information elements in a template that are scope. | |
uint32_t | fbTemplateGetOptionsScope (fbTemplate_t *tmpl) |
Determine number of scope information elements in a template. | |
gboolean | fbTemplateContainsElement (fbTemplate_t *tmpl, const fbInfoElement_t *ex_ie) |
Determine if a template contains a given information element. | |
gboolean | fbTemplateContainsElementByName (fbTemplate_t *tmpl, fbInfoElementSpec_t *spec) |
Determine if a template contains at least one instance of a given information element, specified by name in the template's information model. | |
gboolean | fbTemplateContainsAllElementsByName (fbTemplate_t *tmpl, fbInfoElementSpec_t *spec) |
Determine if a template contains at least one instance of each information element in a given information element specifier array. | |
void | fbTemplateFreeUnused (fbTemplate_t *tmpl) |
Free a template if it is not currently in use by any Session. | |
fbSession_t * | fbSessionAlloc (fbInfoModel_t *model) |
Allocate a transport session state container. | |
void | fbSessionFree (fbSession_t *session) |
Free a transport session state container. | |
void | fbSessionResetExternal (fbSession_t *session) |
Reset the external state (sequence numbers and templates) in a session state container. | |
void | fbSessionSetDomain (fbSession_t *session, uint32_t domain) |
Set the current observation domain on a session. | |
uint32_t | fbSessionGetDomain (fbSession_t *session) |
Retrieve the current domain on a session. | |
gboolean | fbSessionExportTemplate (fbSession_t *session, uint16_t tid, GError **err) |
Export a single external template in the current domain of a given session. | |
gboolean | fbSessionExportTemplates (fbSession_t *session, GError **err) |
Export all external templates in the current domain of a given session. | |
uint16_t | fbSessionAddTemplate (fbSession_t *session, gboolean internal, uint16_t tid, fbTemplate_t *tmpl, GError **err) |
Add a template to a session. | |
gboolean | fbSessionRemoveTemplate (fbSession_t *session, gboolean internal, uint16_t tid, GError **err) |
Remove a template from a session. | |
fbTemplate_t * | fbSessionGetTemplate (fbSession_t *session, gboolean internal, uint16_t tid, GError **err) |
Retrieve a template from a session by ID. | |
fbExporter_t * | fbExporterAllocNet (fbConnSpec_t *spec) |
Allocate an exporting process endpoint for a network connection. | |
fbExporter_t * | fbExporterAllocFile (const char *path) |
Allocate an exporting process endpoint for a named file. | |
fbExporter_t * | fbExporterAllocFP (FILE *fp) |
Allocate an exporting process endpoint for an opened ANSI C file pointer. | |
void | fbExporterSetStream (fbExporter_t *exporter, int sctp_stream) |
Set the SCTP stream for the next message exported. | |
void | fbExporterAutoStream (fbExporter_t *exporter) |
Enable automatic SCTP stream selection for the next message exported. | |
void | fbExporterClose (fbExporter_t *exporter) |
Force the file or socket underlying an exporting process endpoint to close. | |
fbCollector_t * | fbCollectorAllocFile (void *ctx, const char *path, GError **err) |
Allocate a collecting process endpoint for a named file. | |
fbCollector_t * | fbCollectorAllocFP (void *ctx, FILE *fp) |
Allocate a collecting process endpoint for an open file. | |
void * | fbCollectorGetContext (fbCollector_t *collector) |
Retrieve the application context associated with a collector. | |
void | fbCollectorClose (fbCollector_t *collector) |
Close the file or socket underlying a collecting process endpoint. | |
fbListener_t * | fbListenerAlloc (fbConnSpec_t *spec, fbSession_t *session, fbListenerAppInit_fn appinit, fbListenerAppFree_fn appfree, GError **err) |
Allocate a listener. | |
void | fbListenerFree (fbListener_t *listener) |
Free a listener. | |
fBuf_t * | fbListenerWait (fbListener_t *listener, GError **err) |
Wait on a listener. | |
void | fbListenerInterrupt (fbListener_t *listener) |
Cause the current or next call to fbListenerWait to unblock and return. | |
gboolean | fbListenerGetCollector (fbListener_t *listener, fbCollector_t **collector, GError **err) |
fbListenerGetCollector | |
gboolean | fbCollectorClearTranslator (fbCollector_t *collector, GError **err) |
fbCollectorClearTranslator | |
gboolean | fbCollectorSetNetflowV9Translator (fbCollector_t *collector, GError **err) |
fbCollectorSetNetflowV9Translator |
Detailed Description
fixbuf IPFIX protocol library public interface.Include fixbuf/public.h in order to use the public fixbuf API. Calls defined in this header file will not change from version to version after fixbuf 1.0.0, and should not change aside from additions and bugfixes before fixbuf 1.0.0.
This documentation uses IPFIX terminology as defined in RFC XXXX, "Specification of the IPFIX Protocol for the Exchange of IP Traffic Flow Information" (currently work in progress as draft-ietf-ipfix-protocol-24).
Data Types
This file defines the data types and routines required to support IPFIX Exporting Process and IPFIX Collecting Process creation. Each data type is manipulated primarily by routines named "fb" followed by the type name (e.g., "Session", "Collector") followed by a description of the routine's action. The routines operating on the fBuf_t IPFIX Mesaage buffer type are named beginning with "fBuf".The fBuf_t opaque type implements a transcoding IPFIX Message buffer for both export and collection, and is the "core" interface to the fixbuf library.
The fbInfoModel_t opaque type implements an IPFIX Information Model, including both IANA managed Information Elements and vendor-specific Information Elements. The fbTemplate_t opaque type implements an IPFIX Template or an IPFIX Options Template. Both are defined in terms of Information Elements, represented by the fbInfoElement_t public type. An fBuf_t message buffer maintains internal Templates, which represent records within the fixbuf application client, and external Templates, which represent records as they appear on the wire, for use during transcoding.
The state of an IPFIX Transport Session, including IPFIX Message Sequence Number tracking and the internal and external Templates in use within the Session, are maintained by the fbSession_t opaque type.
An Exporting Process' connection to its corresponding Collecting Process is encapsulated by the fbExporter_t opaque type. Exporters may be created to connect via the network using one of the supported IPFIX transport protocols, or to write to IPFIX Files specified by name or by open ANSI C file pointer.
A Collecting Process' connection to a corresponding Exporting Process is encapsulated by the fbCollector_t opaque type. The passive connection used to listen for connections from Exporting Processes is managed by the fbListener_t opaque type; Collectors can be made to read from IPFIX Files specified directly by name or by open ANSI C file pointer, as well.
Network addresses are specified for Exporters, Collectors, and Listeners using the fbConnSpec_t and fbTransport_t public types.
This file also defines the GError error codes used by all the fixbuf types and routines within the FB_ERROR_DOMAIN domain.
Exporter Usage
Each fixbuf application must have a single fbInfoModel_t instance that represents the Information Elements that the application understands. The fbInfoModelAlloc() call allocates a new Information Model with the IANA-managed information elements (current as of the fixbuf release date) preloaded. Additional vendor-specific information elements may be added with fbInfoModelAddElement() and fbInfoModelAddElementArray().To create an Exporter, first create an fbSession_t attached to the application's fbInfoModel_t to hold the Exporter's Transport Session state using fbSessionAlloc(). Create and populate templates for addition to this session using the fbTemplate calls, then add them to the session via fbSessionAddTemplate().
Note that Templates use internal reference counting, so they may be added to multiple sessions, or to the same session using multiple template IDs or multiple domains, or as both an internal and an external template on the same session.
Then create an fbExporter_t to encapsulate the connection to the Collecting Process or the file on disk, using the fbExporterAllocFP(), fbExporterAllocFile(), or fbExporterAllocNet() calls.
With an fbSession_t and an fbExporter_t available, create a buffer for writing via fBufAllocForExport(). Set the internal and external template IDs with fBufSetInternalTemplate() and fBufSetExportTemplate(), and use fBufAppend() to write records into IPFIX Messages and Messages to the output stream.
By default, fBufAppend() will emit an IPFIX Message to the output stream when the end of the message buffer is reached on write. The fBufSetAutomaticMode() call can be used to modify this behavior, causing fBufAppend() to return FB_ERROR_EOM when at end of message. Use this if your application requires manual control of message export. In this case, fBufEmit() will emit a Message to the output stream.
Collector Usage - Reading from IPFIX Files
Using fixbuf to read from IPFIX Files as a Collecting Process is very much like the Export case. Create an fbInfoModel_t and an fbSession_t as above, though you should not define external templates in the new session for collection (instead requiring them to be loaded from templates in the file).Then create an fbCollector_t to encapsulate the file, using the fbCollectorAllocFP() or fbCollectorAllocFile() calls.
With an fbSession_t and an fbCollector_t available, create a buffer for writing via fBufAllocForCollection(). Set the internal template ID with fBufSetInternalTemplate(), and use fBufNext() to read records from IPFIX Messages and Messages from the input stream.
By default, fBufNext() will consume an IPFIX Message from the input stream when the end of the message buffer is reached on read. The fBufSetAutomaticMode() call can be used to modify this behavior, causing fBufNext() to return FB_ERROR_EOM when at end of message. Use this if your application requires manual control of message collection. In this case, fBufNextMessage() will consume a Message from the input stream.
Collector Usage - Listening to the Network
An additional type, fbListener_t, is used to build Collecting Processes to listen for connections from IPFIX Exporting Processes via the network. To use a listener, first create an fbInfoModel_t and an fbSession_t as above, without defining any external templates. Instead of maintaining state for a particular Transport Session, this fbSession_t instance will be used as a template for each Transport Session created by the listener.Then create an fbListener_t to encapsulate a passive socket on the network to wait for connections from Exporting Processes using the fbListenerAlloc() call.
To wait for a connection from an Exporting Process, call fbListenerWait(), which handles the cloning of the fbSession_t, the creation of the fbCollector_t, and the creation of the buffer for reading from that collector, and returns the newly created fBuf_t instance.
Each listener tracks every active collector/buffer (i.e., each active Session) it created; the fbListenerWait() call will return an fBuf_t from which another IPFIX Message may be read if no new connections are available. The preferred parameter may be used to request an fBuf_t to try first, to minimize switching among available Sessions. See the documentation for fbListenerWait() for more details.
Define Documentation
#define FB_CONNSPEC_INIT |
Value:
{ FB_SCTP, NULL, NULL, \ NULL, NULL, NULL, NULL, \ NULL, NULL }
#define FB_ERROR_BUFSZ 5 |
A message was received larger than the collector buffer size.
Should never occur. This condition is checked at the transport layer in case future versions of fixbuf support dynamic buffer sizing.
#define FB_ERROR_DOMAIN g_quark_from_string("fixbufError") |
All fixbuf errors are returned within the FB_ERROR_DOMAIN domain.
#define FB_ERROR_EOF 3 |
End of IPFIX Message stream.
No more messages are available from the transport layer on read, either because the session has closed, or the file has been processed.
#define FB_ERROR_EOM 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.
#define FB_ERROR_IMPL 6 |
The requested feature is not yet implemented.
#define FB_ERROR_IO 7 |
An unspecified I/O error occured.
#define FB_ERROR_IPFIX 4 |
Illegal IPFIX mesaage content on read.
The input stream is malformed, or is not an IPFIX Message after all.
#define FB_ERROR_NETFLOWV9 12 |
Illegal NetflowV9 content on a read.
Can't parse the Netflow header or the stream is not a NetflowV9 stream
#define FB_ERROR_NLREAD 8 |
No data is available for reading from the transport layer.
Either a transport layer read was interrupted, or timed out.
#define FB_ERROR_NLWRITE 9 |
An attempt to write data to the transport layer failed due to closure of the remote end of the connection.
Currently only occurs with the TCP transport layer.
#define FB_ERROR_TMPL 1 |
No template was available for the given template ID.
#define FB_IE_F_ALIEN 0x00000080 |
Information element alien flag.
If set, IE is enterprise-specific and was recieved via an external template at a Collecting Process. It is therefore subject to semantic typing via options (not yet implemented). Do not set this flag on information elements added programmatically to an information model via fbInfoModelAddElement() or fbInfoModelAddElementArray().
#define FB_IE_F_ENDIAN 0x00000001 |
Information element endian conversion flag.
If set, IE is an integer and will be endian-converted on transcode.
#define FB_IE_F_NONE 0x00000000 |
Default treatment flags value.
Provided for initializer convenience. Corresponds to octet-array semantics for a non-reversible, non-alien IE.
#define FB_IE_F_REVERSIBLE 0x00000040 |
Information element reversible flag.
If set for an information element with an enterprise number of 0 (an IETF/IANA IE), adding the information element via fbInfoModelAddElement() or fbInfoModelAddElementArray() will cause a second, reverse information element to be added to the model following the conventions in IETF Internet-Draft draft-ietf-ipfix-biflow-03. Note that the reverse PEN has not yet been assigned, so this implementation uses a provisional reverse IE as defined by the macro FB_IE_PEN_REVERSE.
#define FB_IE_INIT | ( | _name_, | |||
_ent_, | |||||
_num_, | |||||
_len_, | |||||
_flags_ | ) | { {.name = _name_}, 0, _ent_, _num_, _len_, _flags_ } |
Convenience macro for creating fbInfoElement_t static initializers.
Used for creating information element arrays suitable for passing to fbInfoModelAddElementArray().
#define FB_IE_PEN_REVERSE 29305 |
Private enterprise number for reverse information elements (see draft-ietf-ipfix-biflow-03 section 6.1).
If an information element with FB_IE_F_REVERSIBLE and a zero enterprise number (i.e., an IANA-assigned information element) is added to a model, the reverse IE will be generated by setting the enterprise number to this constant.
#define FB_IE_REVERSE_STR "reverse" |
Reverse information element name prefix.
This string is prepended to an information element name, and the first character after this string is capitalized, when generating a reverse information element.
#define FB_IE_REVERSE_STRLEN 7 |
Length of reverse information element name prefix.
#define FB_IE_VENDOR_BIT_REVERSE 0x4000 |
Reverse information element bit for vendor-specific information elements (see draft-ietf-ipfix-biflow-03 section 6.2).
If an information element with FB_IE_F_REVERSIBLE and a non-zero enterprise number (i.e., a vendor-specific information element) is added to a model, the reverse IE number will be generated by ORing this bit with the given forward information element number.
Typedef Documentation
typedef struct fbCollector_st fbCollector_t |
IPFIX Collecting Process endpoint.
Used to collect messages into an associated IPFIX Message Buffer from a remote Exporting Process, or from an IPFIX File. Use this with the fbListener_t structure to implement a full Collecting Process, including Transport Session setup. The internals of this structure are private to libfixbuf.
typedef struct fbExporter_st fbExporter_t |
IPFIX Exporting Process endpoint.
Used to export messages from an associated IPFIX Message Buffer to a remote Collecting Process, or to an IPFIX File. The internals of this structure are private to libfixbuf.
typedef struct fbInfoModel_st fbInfoModel_t |
An IPFIX information model.
Contains information element definitions. The internals of this structure are private to libfixbuf.
typedef struct fbListener_st fbListener_t |
IPFIX Collecting Process session listener.
Used to wait for connections from IPFIX Exporting Processes, and to manage open connections via a select(2)-based mechanism. The internals of this structure are private to libfixbuf.
typedef void(* fbListenerAppFree_fn)(void *ctx) |
Application context free function type for fbListener_t.
Called during fbCollector_t cleanup.
typedef gboolean(* fbListenerAppInit_fn)(fbListener_t *listener, void **ctx, int fd, struct sockaddr *peer, size_t peerlen, GError **err) |
Application context initialization function type for fbListener_t.
This function is called after accept(2) for TCP or SCTP with the peer address in the peer argument. For UDP, it is called during fbListener_t initialization. The application may veto fbCollector_t creation by returning FALSE. The context (returned via out-parameter ctx) will be stored in the fbCollector_t, and is retrievable via a call to fbCollectorGetContext().
typedef struct fbSession_st fbSession_t |
An IPFIX Transport Session state container.
Though Session creation and lifetime are managed by the fbCollector_t and fbExporter_t types, each fBuf_t buffer uses this type to store session state, including internal and external Templates and Message Sequence Number information.
typedef struct fbTemplate_st fbTemplate_t |
An IPFIX Template or Options Template.
Templates define the structure of data records and options records within an IPFIX Message. The internals of this structure are private to libfixbuf.
typedef struct fBuf_st fBuf_t |
An IPFIX message buffer.
Used to encode and decode records from IPFIX Messages. The internals of this structure are private to libfixbuf.
Enumeration Type Documentation
enum fbTransport_en |
Transport protocol for connection specifier.
- Enumerator:
Function Documentation
fbCollector_t* fbCollectorAllocFile | ( | void * | ctx, | |
const char * | path, | |||
GError ** | err | |||
) |
Allocate a collecting process endpoint for a named file.
The underlying file will be opened immediately.
- Parameters:
-
ctx application context; for application use, retrievable by fbCollectorGetContext path path of file to read, or "-" to read standard input. err An error description, set on failure.
- Returns:
- a collecting process endpoint, or NULL on failure.
fbCollector_t* fbCollectorAllocFP | ( | void * | ctx, | |
FILE * | fp | |||
) |
Allocate a collecting process endpoint for an open file.
- Parameters:
-
ctx application context; for application use, retrievable by fbCollectorGetContext fp file pointer to file to read.
- Returns:
- a collecting process endpoint.
gboolean fbCollectorClearTranslator | ( | fbCollector_t * | collector, | |
GError ** | err | |||
) |
fbCollectorClearTranslator
this removes an input translator from a given collector such that it will operate on IPFIX protocol again
- Parameters:
-
collector the collector on which to remove the translator err when an error occurs, a Glib GError structure is set with an error description
- Returns:
- TRUE on success, FALSE on failure
void fbCollectorClose | ( | fbCollector_t * | collector | ) |
Close the file or socket underlying a collecting process endpoint.
No effect on open file endpoints. If the collector is attached to a buffer managed by a listener, the buffer will be removed from the listener (that is, it will not be returned by subsequent fbListenerWait() calls).
- Parameters:
-
collector a collecting process endpoint.
void* fbCollectorGetContext | ( | fbCollector_t * | collector | ) |
Retrieve the application context associated with a collector.
This context is taken from the ctx argument of fbCollectorAllocFile() or fbCollectorAllocFP(), or passed out via the ctx argument to the appinit function argument to fbListenerAlloc().
- Parameters:
-
collector a collecting process endpoint.
- Returns:
- the application context
gboolean fbCollectorSetNetflowV9Translator | ( | fbCollector_t * | collector, | |
GError ** | err | |||
) |
fbCollectorSetNetflowV9Translator
this sets the collector input translator to convert NetFlowV9 into IPFIX for the given collector
- Parameters:
-
collector pointer to the collector state to perform Netflow V9 conversion on err GError structure that holds the error message if an error occurs
- Returns:
- TRUE on success, FALSE on error
fbExporter_t* fbExporterAllocFile | ( | const char * | path | ) |
Allocate an exporting process endpoint for a named file.
The underlying file will not be opened until the first message is emitted from the buffer associated with the exporter.
- Parameters:
-
path pathname of the IPFIX File to write, or "-" to open standard output.
- Returns:
- a new exporting process endpoint
fbExporter_t* fbExporterAllocFP | ( | FILE * | fp | ) |
Allocate an exporting process endpoint for an opened ANSI C file pointer.
- Parameters:
-
fp open file pointer to write to
- Returns:
- a new exporting process endpoint
fbExporter_t* fbExporterAllocNet | ( | fbConnSpec_t * | spec | ) |
Allocate an exporting process endpoint for a network connection.
The remote collecting process is specified by the given connection specifier. The underlying socket connection will not be opened until the first message is emitted from the buffer associated with the exporter.
- Parameters:
-
spec remote endpoint connection specifier
- Returns:
- a new exporting process endpoint
void fbExporterAutoStream | ( | fbExporter_t * | exporter | ) |
Enable automatic SCTP stream selection for the next message exported.
Automatic stream selection is the default; use this call to re-enable it on a given exporter after using fbExporterSetStream(). With automatic stream selection, the minimal behavior specified in the original IPFIX protocol (RFC xxxx) is used: all templates and options templates are exported on stream 0, and all data is exported on stream 1. This call is a no-op for non-SCTP exporters.
- Parameters:
-
exporter an exporting process endpoint.
void fbExporterClose | ( | fbExporter_t * | exporter | ) |
Force the file or socket underlying an exporting process endpoint to close.
No effect on open file endpoints. The file or socket may be reopened on a subsequent message emission from the associated buffer.
- Parameters:
-
exporter an exporting process endpoint.
void fbExporterSetStream | ( | fbExporter_t * | exporter, | |
int | sctp_stream | |||
) |
Set the SCTP stream for the next message exported.
To change the SCTP stream used for export, first emit any message in the exporter's associated buffer with fbufEmit(), then use this call to set the stream for the next message. This call cancels automatic stream selection, use fbExporterAutoStream() to re-enable it. This call is a no-op for non-SCTP exporters.
- Parameters:
-
exporter an exporting process endpoint. sctp_stream SCTP stream to use for next message.
void fbInfoModelAddElement | ( | fbInfoModel_t * | model, | |
fbInfoElement_t * | ie | |||
) |
Add a single information element to an information model.
The information element is assumed to be in "canonical" form; that is, its ref.name field should contain the information element name. The information element and its name are copied into the model; the caller may free or reuse its storage after this call.
See fbInfoModelAddElementArray() for a more convenient method of statically adding information elements to information models.
- Parameters:
-
model An information model ie Pointer to an information element to copy into the model
void fbInfoModelAddElementArray | ( | fbInfoModel_t * | model, | |
fbInfoElement_t * | ie | |||
) |
Add multiple information elements in an array to an information model.
The information elements are assumed to be in "canonical" form; that is, their ref.name fields should contain the information element name. Each information element and its name are copied into the model; the caller may free or reuse its storage after this call.
The ie parameter points to the first information element in an array, usually statically initialized with an array of FB_IE_INIT macros followed by an FB_IE_NULL macro.
- Parameters:
-
model An information model ie Pointer to an IE array to copy into the model
fbInfoModel_t* fbInfoModelAlloc | ( | ) |
Allocate a new information model.
The information model will contain all the default information elements in the IANA-managed number space, and may be extended via fbInfoModelAddElement() and fbInfoModelAddElementArray().
An Information Model is required to create Templates and Sessions. Each application should have only one Information Model.
- Returns:
- a new Information Model
void fbInfoModelFree | ( | fbInfoModel_t * | model | ) |
Free an information model.
Must not be called until all sessions and templates depending on the information model have also been freed; i.e., at application cleanup time.
- Parameters:
-
model An information model
const fbInfoElement_t* fbInfoModelGetElementByName | ( | fbInfoModel_t * | model, | |
const char * | name | |||
) |
Return a pointer to the canonical information element within an information model given the information element name.
The returned information element is owned by the information model and must not be modified.
- Parameters:
-
model An information model name The name of the information element to look up
- Returns:
- The named information element within the model, or NULL if no such element exists.
fbListener_t* fbListenerAlloc | ( | fbConnSpec_t * | spec, | |
fbSession_t * | session, | |||
fbListenerAppInit_fn | appinit, | |||
fbListenerAppFree_fn | appfree, | |||
GError ** | err | |||
) |
Allocate a listener.
The listener will listen on a specified local endpoint, and create a new collecting process endpoint and collection buffer for each incoming connection. Each new buffer will be associated with a clone of a given session state container.
The application may associate context with each created collecting process endpoint, or veto a connection attempt, via a function colled on each connection attempt passed in via the appinit parameter. If this function will create application context, provide a function via the appfree parameter which will free it.
- Parameters:
-
spec local endpoint connection specifier session session state container to clone for each collection buffer created by the listener appinit application connection initiation function. Called on each collection attempt; vetoes connection attempts and creates application context. appfree application context free function. err An error description, set on failure.
- Returns:
- a new listener, or NULL on failure.
void fbListenerFree | ( | fbListener_t * | listener | ) |
Free a listener.
Stops listening on the local endpoint, and frees any open buffers still managed by the listener.
- Parameters:
-
listener a listener
gboolean fbListenerGetCollector | ( | fbListener_t * | listener, | |
fbCollector_t ** | collector, | |||
GError ** | err | |||
) |
fbListenerGetCollector
If a collector is associated with the listener class, this will return a handle to the collector state structure.
- Parameters:
-
listener handle to the listener state collector pointer to a collector state pointer, set on return if there is no error err a GError structure holding an error message on error
- Returns:
- FALSE on error, check err, TRUE on success
void fbListenerInterrupt | ( | fbListener_t * | listener | ) |
Cause the current or next call to fbListenerWait to unblock and return.
Use this from a thread or a signal handler to interrupt a blocked listener.
- Parameters:
-
listener listener to interrupt.
fBuf_t* fbListenerWait | ( | fbListener_t * | listener, | |
GError ** | err | |||
) |
Wait on a listener.
Accepts pending connections from exporting processes. Returns the next collection buffer with available data to read; if the collection buffer returned by the last call to fbListenerWait() is available, it is preferred. Blocks forever (or until fbListenerInterrupt() is called) if no messages or connections are available.
To effectively use fbListenerWait(), the application should set up an session state container with internal templates, call fbListenerWait() to accept a first connection, then read records from the collector buffer to end of message (FB_ERROR_EOM). At end of message, the application should then call fbListenerWait() to accept pending connections or switch to another collector buffer with available data. Note that each collector buffer returned created by fbListenerWait() is set to manual mode using fBufSetAutomaticMode().
- Parameters:
-
listener a listener err An error description, set on failure.
- Returns:
- a collection buffer with available data, or NULL on failure.
uint16_t fbSessionAddTemplate | ( | fbSession_t * | session, | |
gboolean | internal, | |||
uint16_t | tid, | |||
fbTemplate_t * | tmpl, | |||
GError ** | err | |||
) |
Add a template to a session.
If external, adds the template to the current domain, and exports the template if the session is associated with an export buffer. Assigns the template ID given in tid, or assigns a template ID if tid is FB_TID_AUTO.
- Parameters:
-
session A session state container internal TRUE if the template is internal, FALSE if external. tid Template ID to assign, replacing any current template in case of collision; or FB_TID_AUTO to assign a new tId. tmpl Template to add err An error description, set on failure
- Returns:
- the template ID of the added template, or 0 on failure.
fbSession_t* fbSessionAlloc | ( | fbInfoModel_t * | model | ) |
Allocate a transport session state container.
The new session is associated with the given information model, contains no templates, and is usable either for collection or export.
Each fbExporter_t, fbListener_t, and fbCollector_t must have its own session; session state cannot be shared.
- Parameters:
-
model An information model
- Returns:
- a new, empty session state container.
gboolean fbSessionExportTemplate | ( | fbSession_t * | session, | |
uint16_t | tid, | |||
GError ** | err | |||
) |
Export a single external template in the current domain of a given session.
Writes the template to the associated export buffer. May cause a message to be emitted if the associated export buffer is in automatic mode, or return with FB_ERROR_EOM if the associated export buffer is not in automatic mode.
- Parameters:
-
session a session state container associated with an export buffer tid template ID within current domain to export err an error description, set on failure.
- Returns:
- TRUE on success, FALSE on failure.
gboolean fbSessionExportTemplates | ( | fbSession_t * | session, | |
GError ** | err | |||
) |
Export all external templates in the current domain of a given session.
Writes templates to the associated export buffer. May cause a message to be emitted if the associated export buffer is in automatic mode, or return with FB_ERROR_EOM if the associated export buffer is not in automatic mode.
- Parameters:
-
session a session state container associated with an export buffer err an error description, set on failure.
- Returns:
- TRUE on success, FALSE on failure.
void fbSessionFree | ( | fbSession_t * | session | ) |
Free a transport session state container.
This is done automatically when freeing the listener or buffer with which the session is associated. Use this call if a session needs to be destroyed before it is associated.
- Parameters:
-
session session state container to free.
uint32_t fbSessionGetDomain | ( | fbSession_t * | session | ) |
Retrieve the current domain on a session.
- Parameters:
-
session a session state container
- Returns:
- the ID of the session's current observation domain
fbTemplate_t* fbSessionGetTemplate | ( | fbSession_t * | session, | |
gboolean | internal, | |||
uint16_t | tid, | |||
GError ** | err | |||
) |
Retrieve a template from a session by ID.
If external, retrieves the template within the current domain.
- Parameters:
-
session A session state container internal TRUE if the template is internal, FALSE if external. tid ID of the template to retrieve. err An error description, set on failure.
- Returns:
- The template with the given ID, or NULL on failure.
gboolean fbSessionRemoveTemplate | ( | fbSession_t * | session, | |
gboolean | internal, | |||
uint16_t | tid, | |||
GError ** | err | |||
) |
Remove a template from a session.
If external, removes the template from the current domain, and exports a template revocation set if the session is associated with an export buffer.
- Parameters:
-
session A session state container internal TRUE if the template is internal, FALSE if external. tid Template ID to remove. err An error description, set on failure
- Returns:
- TRUE on success, FALSE on failure.
void fbSessionResetExternal | ( | fbSession_t * | session | ) |
Reset the external state (sequence numbers and templates) in a session state container.
FIXME: Verify that this call actually makes sense; either that a session is reassociatable with a new collector, or that you need to do this when reassociating a collector with a connection. Once this is done, rewrite this documentation
- Parameters:
-
session session state container to reset
void fbSessionSetDomain | ( | fbSession_t * | session, | |
uint32_t | domain | |||
) |
Set the current observation domain on a session.
The domain is used to scope sequence numbers and external templates. This is called automatically during collection, but must be called to set the domain for export before adding external templates or writing records.
Notice that a domain change does not automatically cause any associated export buffers to emit messages; a domain change takes effect with the next message started. Therefore, call fBufEmit() before setting the domain on the buffer's associated session.
- Parameters:
-
session a session state container domain ID of the observation domain to set
fbTemplate_t* fbTemplateAlloc | ( | fbInfoModel_t * | model | ) |
Allocate a new empty template.
The template will be associated with the given Information Model, and only able to use Information Elements defined within that Information Model. Templates may be associated with multiple sessions, with different template IDs each time, and as such are reference counted and owned by sessions. A template must be associated with at least one session or it will be leaked; each template is freed after its last associated session is freed.
Use fbTemplateAppend(), fbTemplateAppendSpec(), and fbTemplateAppendSpecArray() to "fill in" a template after creating it, and before associating it with any session.
- Parameters:
-
model An information model
- Returns:
- a new, empty Template.
gboolean fbTemplateAppend | ( | fbTemplate_t * | tmpl, | |
fbInfoElement_t * | ex_ie, | |||
GError ** | err | |||
) |
Append an information element to a template.
The information element is taken to be an example; the canonical element from the template's associated model is looked up by enterprise and element number and copied. If no information element exists in the model with the given enterprise and element number, it is copied to the model with the name "_alienInformationElement".
This call is intended primarily for use by fBuf_t's template reader, but can also be useful to simulate receipt of templates over the wire.
- Parameters:
-
tmpl Template to append information element to ex_ie Example IE to add to the template err an error description, set on failure.
- Returns:
- TRUE on success, FALSE on failure.
gboolean fbTemplateAppendSpec | ( | fbTemplate_t * | tmpl, | |
fbInfoElementSpec_t * | spec, | |||
uint32_t | flags, | |||
GError ** | err | |||
) |
Append an information element described by specifier to a template.
The information element named by the specifier is copied from the template's associated model, and the length and flags are overriden from the specifier.
- Parameters:
-
tmpl Template to append information element to. spec Specifier describing information element to append. flags Application flags. Must match one bit of spec flags word or the append will be silently skipped. Used for building multiple templates with different information element features from a single specifier. err an error description, set on failure.
- Returns:
- TRUE on success, FALSE on failure.
gboolean fbTemplateAppendSpecArray | ( | fbTemplate_t * | tmpl, | |
fbInfoElementSpec_t * | spec, | |||
uint32_t | flags, | |||
GError ** | err | |||
) |
Append information elements described by a specifier array to a template.
The information elements named by the specifiers are copied from the template's associated model, and the length and flags are overriden from each specifier. The array is read until the FB_IESPEC_NULL convenience macro is encountered.
- Parameters:
-
tmpl Template to append information element to. spec Pointer to first specifier in specifier array to append. flags Application flags. Must contain all bits of spec flags word or the append will be silently skipped. Used for building multiple templates with different information element features from a single specifier. err an error description, set on failure.
- Returns:
- TRUE on success, FALSE on failure.
gboolean fbTemplateContainsAllElementsByName | ( | fbTemplate_t * | tmpl, | |
fbInfoElementSpec_t * | spec | |||
) |
Determine if a template contains at least one instance of each information element in a given information element specifier array.
- Parameters:
-
tmpl Template to search spec Pointer to specifier array to search for
- Returns:
- TRUE if the template contains all the given IEs
gboolean fbTemplateContainsElement | ( | fbTemplate_t * | tmpl, | |
const fbInfoElement_t * | ex_ie | |||
) |
Determine if a template contains a given information element.
Matches against information element private enterprise number, number, and multiple-IE index (i.e., to determine if a given template contains six instances of a given information element, set ex_ie->midx = 5 before this call).
- Parameters:
-
tmpl Template to search ex_ie Pointer to an information element to search for
- Returns:
- TRUE if the template contains the given IE
gboolean fbTemplateContainsElementByName | ( | fbTemplate_t * | tmpl, | |
fbInfoElementSpec_t * | spec | |||
) |
Determine if a template contains at least one instance of a given information element, specified by name in the template's information model.
- Parameters:
-
tmpl Template to search spec Specifier of information element to search for
- Returns:
- TRUE if the template contains the given IE
uint32_t fbTemplateCountElements | ( | fbTemplate_t * | tmpl | ) |
Determine number of information elements in a template.
- Parameters:
-
tmpl A template
- Returns:
- information element count
void fbTemplateFreeUnused | ( | fbTemplate_t * | tmpl | ) |
Free a template if it is not currently in use by any Session.
Use this to clean up while creating templates in case of error.
- Parameters:
-
tmpl template to free
uint32_t fbTemplateGetOptionsScope | ( | fbTemplate_t * | tmpl | ) |
Determine number of scope information elements in a template.
The template is an options template if nonzero.
- Parameters:
-
tmpl A template
- Returns:
- scope information element count
void fbTemplateSetOptionsScope | ( | fbTemplate_t * | tmpl, | |
uint16_t | scope_count | |||
) |
Set the number of information elements in a template that are scope.
This causes the template to become an options template, and must be called after all the scope information elements have been appended to the template.
- Parameters:
-
tmpl Template to set scope on scope_count Number of scope information elements
fBuf_t* fBufAllocForCollection | ( | fbSession_t * | session, | |
fbCollector_t * | collector | |||
) |
Allocate a new buffer for collection.
Associates the buffer with a given session and collecting process endpoint; these become owned by the buffer.
- Parameters:
-
session a session initialized with appropriate internal templates collector an collecting process endpoint
- Returns:
- a new IPFIX message buffer, owning the session and collector, for collection use via fBufNext() and fBufNextMessage().
fBuf_t* fBufAllocForExport | ( | fbSession_t * | session, | |
fbExporter_t * | exporter | |||
) |
Allocate a new buffer for export.
Associates the buffer with a given session and exporting process endpoint; these become owned by the buffer.
- Parameters:
-
session a session initialized with appropriate internal and external templates exporter an exporting process endpoint
- Returns:
- a new IPFIX message buffer, owning the session and exporter, for export use via fBufAppend() and fBufEmit().
gboolean fBufAppend | ( | fBuf_t * | fbuf, | |
uint8_t * | recbase, | |||
size_t | recsize, | |||
GError ** | err | |||
) |
Append a record to a buffer.
Uses the present internal template set via fBufSetInternalTemplate() to describe the record of size recsize located in memory at recbase. Uses the present export template set via fBufSetExportTemplate() to describe the record structure to be written to the buffer. Information Elements present in the external template that are not present in the internal template are transcoded into the message as zeroes. If the buffer is in automatic mode, may cause a message to be emitted via fBufEmit() if there is insufficient space in the buffer for the record.
If the internal template contains any variable length Information Elements, those must be represented in the record by fbVarfield_t structures.
- Parameters:
-
fbuf an IPFIX message buffer recbase pointer to internal record recsize size of internal record in bytes err an error description, set on failure. Must not be NULL, as it is used internally in automatic mode to detect message restart.
- Returns:
- TRUE on success, FALSE on failure.
gboolean fBufEmit | ( | fBuf_t * | fbuf, | |
GError ** | err | |||
) |
Emit the message currently in a buffer using the associated exporting process endpoint.
- Parameters:
-
fbuf an IPFIX message buffer err an error description, set on failure.
- Returns:
- TRUE on success, FALSE on failure.
void fBufFree | ( | fBuf_t * | fbuf | ) |
Free a buffer.
Also frees any associated session, exporter, or collector, closing exporting process or collecting process endpoint connections and removing collecting process endpoints from any listeners, as necessary.
- Parameters:
-
fbuf an IPFIX message buffer
fbTemplate_t* fBufGetCollectionTemplate | ( | fBuf_t * | fbuf, | |
uint16_t * | ext_tid | |||
) |
Retrieve the external template used to read the last record from the buffer.
If no record has been read, returns NULL. Stores the external template ID within the current domain in ext_tid, if not NULL.
This routine is not particularly useful to applications, as it would be called after the record described by the external template had been transcoded, and as such could not be used to select an appropriate internal template for a given external template. However, it is used by fBufNextCollectionTemplate(), and may be useful in certain contexts, so is made public.
Usually, you'll want to use fBufNextCollectionTemplate() instead.
- Parameters:
-
fbuf an IPFIX message buffer ext_tid pointer to external template ID storage, or NULL.
- Returns:
- the external template describing the last record read.
fbCollector_t* fBufGetCollector | ( | fBuf_t * | fbuf | ) |
Retrieve the collecting process endpoint associated with a buffer.
The buffer must have been allocated with fBufAllocForCollection(); otherwise, returns NULL.
- Parameters:
-
fbuf an IPFIX message buffer
- Returns:
- the associated collecting process endpoint
fbExporter_t* fBufGetExporter | ( | fBuf_t * | fbuf | ) |
Retrieve the exporting process endpoint associated with a buffer.
The buffer must have been allocated with fBufAllocForExport(); otherwise, returns NULL.
- Parameters:
-
fbuf an IPFIX message buffer
- Returns:
- the associated exporting process endpoint
uint32_t fBufGetExportTime | ( | fBuf_t * | fbuf | ) |
Retrieve the export time on the message currently in a buffer.
- Parameters:
-
fbuf an IPFIX message buffer
- Returns:
- the export time in epoch seconds.
fbSession_t* fBufGetSession | ( | fBuf_t * | fbuf | ) |
Retrieve the session associated with a buffer.
- Parameters:
-
fbuf an IPFIX message buffer
- Returns:
- the associated session
gboolean fBufNext | ( | fBuf_t * | fbuf, | |
uint8_t * | recbase, | |||
size_t * | recsize, | |||
GError ** | err | |||
) |
Retrieve a record from a buffer.
Uses the external template taken from the message to read the next record available from a data set in the message. Copies the record to a buffer at recbase, with a maximum record size pointed to by recsize, described by the present internal template set via fBufSetInternalTemplate(). Reads and processes any templates and options templates between the last record read (or beginning of message) and the next data record. Information Elements present in the internal template that are not present in the external template are transcoded into the record at recbase as zeroes. If the buffer is in automatic mode, may cause a message to be read via fBufNextMessage() if there are no more records available in the message buffer.
If the internal template contains any variable length Information Elements, those must be represented in the record at recbase by fbVarfield_t structures.
- Parameters:
-
fbuf an IPFIX message buffer recbase pointer to internal record buffer; will contain record data after call. recsize On call, pointer to size of internal record buffer in bytes. Contains number of bytes actually transcoded at end of call. err an error description, set on failure. Must not be NULL, as it is used internally in automatic mode to detect message restart.
- Returns:
- TRUE on success, FALSE on failure.
fbTemplate_t* fBufNextCollectionTemplate | ( | fBuf_t * | fbuf, | |
uint16_t * | ext_tid, | |||
GError ** | err | |||
) |
Retrieve the external template that will be used to read the next record from the buffer.
If no next record is available, returns NULL. Stores the external template ID within the current domain in ext_tid, if not NULL. Reads and processes any templates and options templates between the last record read (or beginning of message) and the next data record. If the buffer is in automatic mode, may cause a message to be read via fBufNextMessage() if there are no more records available in the message buffer.
- Parameters:
-
fbuf an IPFIX message buffer ext_tid pointer to external template ID storage, or NULL. err an error description, set on failure. Must not be NULL, as it is used internally in automatic mode to detect message restart.
- Returns:
- the external template describing the last record read.
gboolean fBufNextMessage | ( | fBuf_t * | fbuf, | |
GError ** | err | |||
) |
Read a new message into a buffer using the associated collecting process endpoint.
Called by fBufNext() on end of message in automatic mode; should be called after an FB_ERROR_EOM return from fBufNext in manual mode, or to skip the current message and go on to the next in the stream.
- Parameters:
-
fbuf an IPFIX message buffer err an error description, set on failure.
- Returns:
- TRUE on success, FALSE on failure.
void fBufSetAutomaticMode | ( | fBuf_t * | fbuf, | |
gboolean | automatic | |||
) |
Set the automatic mode flag on a buffer.
In automatic mode, a call to fBufAppend() or fbSessionExportTemplates() that overruns the available space in the buffer will cause a call to fBufEmit() to emit the message in the buffer to the exporter before starting a new message; and a call to fBufNext() that overruns the buffer will cause a call to fBufNextMessage() to read another message from the collector before attempting to read a record. In manual mode, end of message on any buffer read/write call results in FB_ERROR_EOM. Buffers are created in automatic mode by default.
- Parameters:
-
fbuf an IPFIX message buffer automatic TRUE for this buffer to be automatic, FALSE for manual.
void fBufSetCollector | ( | fBuf_t * | fbuf, | |
fbCollector_t * | collector | |||
) |
Associate an collecting process endpoint with a buffer.
The collector will be used to read IPFIX messgaes from a transport. The collector becomes owned by the buffer; any previous collector associated with the buffer is closed if necessary and freed.
- Parameters:
-
fbuf an IPFIX message buffer collector an collecting process endpoint
void fBufSetExporter | ( | fBuf_t * | fbuf, | |
fbExporter_t * | exporter | |||
) |
Associate an exporting process endpoint with a buffer.
The exporter will be used to write IPFIX messgaes to a transport. The exporter becomes owned by the buffer; any previous exporter associated with the buffer is closed if necessary and freed.
- Parameters:
-
fbuf an IPFIX message buffer exporter an exporting process endpoint
gboolean fBufSetExportTemplate | ( | fBuf_t * | fbuf, | |
uint16_t | ext_tid, | |||
GError ** | err | |||
) |
Set the external template for export on a buffer to the given template ID.
The external template describes the record that will be written to the IPFIX message. The buffer must be initialized for export. The given ID is scoped to the observation domain of the associated session (see fbSessionSetDomain()), and must identify a current external template for the current domain in the buffer's associated session.
An export template must be set on a buffer before calling fBufAppend().
- Parameters:
-
fbuf an IPFIX message buffer ext_tid template ID of the new external template within the current domain. err An error description, set on failure.
- Returns:
- TRUE on success, FALSE on failure.
void fBufSetExportTime | ( | fBuf_t * | fbuf, | |
uint32_t | extime | |||
) |
Set the export time on the message currently in a buffer.
This will be used as the export time of the message created by the first call to fBufAppend() after the current message, if any, is emitted. Use 0 for the export time to cause the export time to be taken from the system clock at message creation time.
- Parameters:
-
fbuf an IPFIX message buffer extime the export time in epoch seconds.
gboolean fBufSetInternalTemplate | ( | fBuf_t * | fbuf, | |
uint16_t | int_tid, | |||
GError ** | err | |||
) |
Set the internal template on a buffer to the given template ID.
The internal template describes the format of the record pointed to by the recbase parameter to fBufAppend() (for export) and fBufNext() (for collection). The given template ID must identify a current internal template in the buffer's associated session.
An internal template must be set on a buffer before calling fBufAppend() or fBufNext().
- Parameters:
-
fbuf an IPFIX message buffer int_tid template ID of the new internal template err An error description, set on failure.
- Returns:
- TRUE on success, FALSE on failure.