bgpstream.h

Header file that exposes the public interface of bgpstream.

See bgpstream_record.h and bgpstream_elem.h for the public interfaces of bgpstream_record and bgpstream_elem respectively.

Author
Chiara Orsini

Public Macros

BGPSTREAM_FOREVER

Used to specify an interval that never ends (i.e., when processing in live mode).

Public Opaque Data Structures

typedef struct struct_bgpstream_t bgpstream_t

Opaque handle that represents a BGP Stream instance.

Public Enums

enum bgpstream_filter_type_t

The type of the filter to be applied.

Values:

BGPSTREAM_FILTER_TYPE_PROJECT = 1

Filter records based on associated project (e.g.

‘ris’)

BGPSTREAM_FILTER_TYPE_COLLECTOR = 2

Filter records based on collector (e.g.

‘rrc01’)

BGPSTREAM_FILTER_TYPE_RECORD_TYPE = 3

Filter records based on record type (e.g.

‘updates’)

BGPSTREAM_FILTER_TYPE_ELEM_PEER_ASN = 4

Filter elems based on peer ASN.

BGPSTREAM_FILTER_TYPE_ELEM_PREFIX = 5

Filter elems based on prefix.

BGPSTREAM_FILTER_TYPE_ELEM_COMMUNITY = 6

Filter elems based on the community attribute.

enum bgpstream_data_interface_id_t

Data Interface IDs.

Values:

BGPSTREAM_DATA_INTERFACE_BROKER = 1

Broker data interface.

BGPSTREAM_DATA_INTERFACE_SINGLEFILE = 2

Customlist interface.

BGPSTREAM_DATA_INTERFACE_CSVFILE = 3

CSV file interface.

BGPSTREAM_DATA_INTERFACE_MYSQL = 4

MySQL data interface.

BGPSTREAM_DATA_INTERFACE_SQLITE = 5

SQLITE file interface.

Public Data Structures

typedef struct struct_bgpstream_data_interface_info bgpstream_data_interface_info_t

Structure that contains information about a BGP Stream Data Interface.

typedef struct struct_bgpstream_data_interface_option bgpstream_data_interface_option_t

Structure that represents BGP Stream Data Interface Option.

Public API Functions

bgpstream_t *bgpstream_create()

Create a new BGP Stream instance.

Return
a pointer to a BGP Stream instance if successful, NULL otherwise

void bgpstream_add_filter(bgpstream_t *bs, bgpstream_filter_type_t filter_type, const char *filter_value)

Add a filter in order to select a subset of the bgp data available.

Parameters
  • bs -

    pointer to a BGP Stream instance to filter

  • filter_type -

    the type of the filter to apply

  • filter_value -

    the value to set the filter to

void bgpstream_add_rib_period_filter(bgpstream_t *bs, uint32_t period)

Add a filter to configure the minimum bgp time interval between RIB files that belong to the same collector.

This information can be changed at run time.

Parameters
  • bs -

    pointer to a BGP Stream instance to filter

  • period -

    time period (if zero, all available RIBs are processed)

void bgpstream_add_interval_filter(bgpstream_t *bs, uint32_t begin_time, uint32_t end_time)

Add a filter to select a specific time range from the BGP data available.

If end_time is set to BGPSTREAM_FOREVER, the stream will be set to live mode, and will process data forever.

Parameters
  • bs -

    pointer to a BGP Stream instance to filter

  • begin_time -

    the first time that will match the filter (inclusive)

  • end_time -

    the last time that will match the filter (inclusive)

int bgpstream_get_data_interfaces(bgpstream_t *bs, bgpstream_data_interface_id_t **if_ids)

Get a list of data interfaces that are currently supported.

Return
the number of elements the the if_ids array
Note
the returned array belongs to BGP Stream. It must not be freed by the user.
Parameters
  • bs -

    pointer to the BGP Stream instance in the returned array

  • if_ids -

    set to a borrowed pointer to an array of bgpstream_datasource_type_t values

bgpstream_data_interface_id_t bgpstream_get_data_interface_id_by_name(bgpstream_t *bs, const char *name)

Get the ID of the data interface with the given name.

Return
the ID of the data interface with the given name, 0 if no matching interface was found
Parameters
  • name -

    name of the data interface to retrieve the ID for

bgpstream_data_interface_info_t *bgpstream_get_data_interface_info(bgpstream_t *bs, bgpstream_data_interface_id_t if_id)

Get information for the given data interface.

Return
borrowed pointer to an interface info structure
Parameters
  • bs -

    pointer to a BGP Stream instance

  • if_id -

    ID of the interface to get the name for

int bgpstream_get_data_interface_options(bgpstream_t *bs, bgpstream_data_interface_id_t if_id, bgpstream_data_interface_option_t **opts)

Get a list of valid option types for the given data interface.

Return
the number of elements in the opts array
Note
the returned array belongs to BGP Stream. It must not be freed by the user.
Parameters
  • bs -

    pointer to a BGP Stream instance

  • if_id -

    ID of the interface to get option names for in the returned array

  • opts -

    set to a borrowed pointer to an array of options

bgpstream_data_interface_option_t *bgpstream_get_data_interface_option_by_name(bgpstream_t *bs, bgpstream_data_interface_id_t if_id, const char *name)

Get the data interface option for the given data interface and option name.

Return
pointer to the option information with the given name, NULL if either the interface ID is not valid, or the name does not match any options
Parameters
  • bs -

    pointer to a BGP Stream instance

  • if_id -

    ID of the interface to get option info for

  • name -

    name of the option to retrieve

void bgpstream_set_data_interface_option(bgpstream_t *bs, bgpstream_data_interface_option_t *option_type, const char *option_value)

Set a data interface option.

Use the bgpstream_get_data_interface_options function to discover the set of options for an interface.

Parameters
  • bs -

    pointer to a BGP Stream instance to configure

  • option_type -

    pointer to the option to set

  • option_value -

    value to set the option to

bgpstream_data_interface_id_t bgpstream_get_data_interface_id(bgpstream_t *bs)

Get the ID of the currently active data interface.

If no data interface has been explicitly set, this function will return the ID of the default data interface.

Return
the ID of the currently active data interface
Parameters
  • bs -

    pointer to a BGP Stream instance

void bgpstream_set_data_interface(bgpstream_t *bs, bgpstream_data_interface_id_t if_id)

Set the data interface that BGP Stream uses to find BGP data.

Parameters
  • bs -

    pointer to a BGP Stream instance to configure

  • if_id -

    ID of the data interface to use

void bgpstream_set_live_mode(bgpstream_t *bs)

Configure the interface to block waiting for new data instead of returning end-of-stream if no more data is available.

Live mode is implicitly enabled when an interval end is set to BGPSTREAM_FOREVER.

Parameters
  • bs -

    pointer to a BGP Stream instance to put into live mode

int bgpstream_start(bgpstream_t *bs)

Start the given BGP Stream instance.

This function must be called after all configuration functions, and before the first call to bgpstream_get_next_record.

Return
0 if the stream was started successfully, -1 otherwise
Parameters
  • bs -

    pointer to a BGP Stream instance to start

int bgpstream_get_next_record(bgpstream_t *bs, bgpstream_record_t *record)

Retrieve from the stream, the next record that matches configured filters.

The record passed to this function may be reused for subsequent calls if state for previous records is not needed (i.e. the records are processed independently of each other). If records are not processed independently, then a new record must be created for each call to this function.

Return
>0 if a record was read successfully, 0 if end-of-stream has been reached, <0 if an error occurred.
Parameters
  • bs -

    pointer to a BGP Stream instance to get record from

  • record -

    pointer to a bgpstream record instance created using bgpstream_record_create

void bgpstream_stop(bgpstream_t *bs)

Stop the given BGP Stream instance.

Parameters
  • bs -

    pointer to a BGP Stream instance to stop

void bgpstream_destroy(bgpstream_t *bs)

Destroy the given BGP Stream instance.

Parameters
  • bs -

    pointer to a BGP Stream instance to destroy

struct struct_bgpstream_data_interface_info
#include <bgpstream.h>

Structure that contains information about a BGP Stream Data Interface.

Public Members

bgpstream_data_interface_id_t id

The ID of this data interface.

char *name

The name of this data interface.

char *description

A human-readable description of this data interface.

struct struct_bgpstream_data_interface_option
#include <bgpstream.h>

Structure that represents BGP Stream Data Interface Option.

Public Members

bgpstream_data_interface_id_t if_id

The ID of the data interface that this option applies to.

int id

An internal, interface-specific ID for this option.

char *name

The human-readable name of the option.

char *description

A human-readable description of the option.