libipa

The IPA client library. More...

Classes
struct	IPAContext
	IPA Context data structure. More...
struct	IPAAssoc
	An IPA result record containing an IP address range, a label for that range,and a scalar value associated with the range. More...
Enumerations
enum	IPAStatus {   IPA_OK = 0, IPA_ERR_NOTFOUND, IPA_ERR_FILEIO, IPA_ERR_SQL,   IPA_ERR_INVALID, IPA_ERR_UNKNOWN }
	The following error return values are defined for IPA:. More...
enum	IPACatalogType {   IPA_CAT_NONE = 0, IPA_CAT_SET, IPA_CAT_BAG, IPA_CAT_PMAP,   IPA_CAT_MMAP }
	IPA catalogs hold one of the following types of data. More...
enum	IPAContextState {   IPA_STATE_INITIAL = 0, IPA_STATE_EXPORT, IPA_STATE_IMPORT, IPA_STATE_QUERY,   IPA_STATE_QUERY_DONE }
Functions
int	ipa_create_context (IPAContext **ipa, char *db_uri)
	Create a handle to an IPA data store.
void	ipa_destroy_context (IPAContext **ipa)
	Destroy an IPA context that was created with ipa_create_context().
void	ipa_begin (IPAContext *ipa)
	Begin an IPA transaction.
void	ipa_commit (IPAContext *ipa)
	Commit (complete) an IPA transaction.
void	ipa_rollback (IPAContext *ipa)
	Rollback (abort) an IPA transaction.
int	ipa_add_dataset (IPAContext *ipa, const char *catname, const char *catdesc, IPACatalogType type, const char *begin, const char *end)
	Add a new IPA dataset to the database.
int	ipa_add_assoc (IPAContext *ipa, uint32_t addr1, uint32_t addr2, char *label, uint64_t value)
	Add an IP range to a dataset with an optional label and/or scalar value.
int	ipa_add_cidr (IPAContext *ipa, uint32_t addr, uint32_t prefix, char *label, uint64_t value)
	Convenience function for adding CIDRized IP ranges.
int	ipa_get_dataset (IPAContext *ipa, const char *catalog_name, const char *dataset_time)
	Retrieve a dataset record.
int	ipa_get_assoc (IPAContext *ipa, IPAAssoc *assoc)
	Retrieve the next range in an open dataset.

---

Detailed Description

The IPA client library.

libipa provides functions for querying and managing IP address data and metadata in an IPA data store. To use libipa, include <ipa/ipa.h> in your application code, and link your application against the libipa shared libraries.

Interface

The IPAContext

Before you can communicate with the IPA data store, your application must first create an IPAContext using ipa_create_context(). After this context is created, you can invoke other methods. Once your application is finished talking to IPA, use ipa_destroy_context() to free resources associated with the IPA transaction.

Transactions

IPA applications are responsible for transactional integrity. IPA provides methods for applications to begin, commit, and rollback (abort) transactions.

Importing a Dataset

To import data into IPA, call ipa_add_dataset() to create the empty dataset,then call ipa_add_assoc() for every IP range association in that dataset. Once all associations are added, call ipa_commit() to complete the transaction.

Exporting a Dataset

To export a single IPA dataset, call ipa_get_dataset() to load the dataset into the IPAContext. Then, call ipa_get_assoc() to retrieve each association in the dataset.

Advanced Queries

Users who are familiar with the IPA data model may wish to execute custom queries. To do so, follow this example:

IPAContext *ipa      = NULL;
const char *val      = NULL;

if ( ipa_create_context(&ipa, ipa_db_uri) != IPA_OK) {
   g_error("couldn't create IPA context");
}

g_string_printf(ipa->sql,
    "SELECT d.dataset_id, d.t_begin, d.t_end, "
    "date_trunc('second', d.ctime), "
    "date_trunc('second', d.mtime), "
    "count(a.range) "
    "FROM ipa.catalog c "
    "LEFT JOIN ipa.dataset d on c.catalog_id=d.catalog_id "
    "LEFT JOIN ipa.assoc a on d.dataset_id=a.dataset_id "
    "WHERE c.name='%s' "
    "GROUP BY d.dataset_id, d.t_begin, d.t_end, "
    "d.ctime, d.mtime;",
    "test_catalog");
ipa_statement_query(ipa);
IPA_CHECK_ERR(err, "error retrieving dataset", IPA_ERR_SQL);
while (adb_rs_next(ipa->rs, &err)) {
    adb_rs_fetch(ipa->rs, 0, &val, &err);
    IPA_CHECK_ERR(err, "error fetching from SQL result set", IPA_ERR_SQL);
    /* the first field is now stored in "val", do something with it */
    adb_rs_fetch(ipa->rs, 1, &val, &err);
    IPA_CHECK_ERR(err, "error fetching from SQL result set", IPA_ERR_SQL);
    /* the second field is now stored in "val", do something with it */
    
    /* ... */
}

---

Enumeration Type Documentation

enum IPAStatus

The following error return values are defined for IPA:.

Enumerator:

IPA_OK	No errors occurred.
IPA_ERR_NOTFOUND	A required resource was was not found.
IPA_ERR_FILEIO	File input/output error.
IPA_ERR_SQL	Error from the IPA relational database.
IPA_ERR_INVALID	An invalid argument was given.
IPA_ERR_UNKNOWN	Unknown error.

enum IPACatalogType

IPA catalogs hold one of the following types of data.

Enumerator:

IPA_CAT_NONE	Catalog hasn't been assigned a type yet.
IPA_CAT_SET	Catalog contains IPset data.
IPA_CAT_BAG	Catalog contains Bag data.
IPA_CAT_PMAP	Catalog contains prefix map data.
IPA_CAT_MMAP	Catalog contains multimap data.

enum IPAContextState

Enumerator:

IPA_STATE_INITIAL	Context is ready.
IPA_STATE_EXPORT	Export operation in progress.
IPA_STATE_IMPORT	Import operation in progress.
IPA_STATE_QUERY	Query operation in progresss.
IPA_STATE_QUERY_DONE	Query operation is complete.

---

Function Documentation

int ipa_create_context	(	IPAContext **	ipa,
		char *	db_uri
	)

Create a handle to an IPA data store.

Parameters:

	ipa	The address of an IPAContext pointer.
	db_uri	The URI of an IPA data store. URIs should be of the form driver://username:password@hostname/database e.g. postgresql://ipauser:secret@dbserver/ipa

Returns:

IPA error status.

void ipa_destroy_context

(

IPAContext **

ipa

)

Destroy an IPA context that was created with ipa_create_context().

Parameters:

ipa

The address of an IPAContext pointer.

Returns:

IPA error status.

void ipa_begin

(

IPAContext *

ipa

)

Begin an IPA transaction.

Parameters:

ipa

A valid IPA context.

void ipa_commit

(

IPAContext *

ipa

)

Commit (complete) an IPA transaction.

Parameters:

ipa

A valid IPA context.

void ipa_rollback

(

IPAContext *

ipa

)

Rollback (abort) an IPA transaction.

Parameters:

ipa

A valid IPA context.

int ipa_add_dataset	(	IPAContext *	ipa,
		const char *	catname,
		const char *	catdesc,
		IPACatalogType	type,
		const char *	begin,
		const char *	end
	)

Add a new IPA dataset to the database.

Parameters:

	ipa	A valid IPA context.
	catname	The name of the catalog to add the new dataset to.
	catdesc	A short description of the catalog (for new catalogs)
	type	The type of the catalog as a IPACatalogType value
	begin	Beginning of the validity date range for this dataset.
	end	End of the validity date range for this dataset.

Returns:

IPA error status.

int ipa_add_assoc	(	IPAContext *	ipa,
		uint32_t	addr1,
		uint32_t	addr2,
		char *	label,
		uint64_t	value
	)

Add an IP range to a dataset with an optional label and/or scalar value.

Parameters:

	ipa	A valid IPA context.
	addr1	The start address of the IP range.
	addr2	The end address of the IP range.
	label	The name of the label to assign to the IP range. For IPA_CAT_SET and IPA_CAT_BAG catalog types, this parameter is ignored.
	value	The scalar value to assign to the labeled range.

Returns:

IPA error status.

int ipa_add_cidr	(	IPAContext *	ipa,
		uint32_t	addr,
		uint32_t	prefix,
		char *	label,
		uint64_t	value
	)

Convenience function for adding CIDRized IP ranges.

Parameters:

	ipa	A valid IPA context.
	addr	The start address of the block.
	prefix	The number of prefix bits.
	label	The name of the label to assign to the IP range.
	value	The scalar value to assign to the labeled range.

Returns:

IPA error status.

int ipa_get_dataset	(	IPAContext *	ipa,
		const char *	catalog_name,
		const char *	dataset_time
	)

Retrieve a dataset record.

Parameters:

	ipa	A valid IPA context.
	catalog_name	The name of the catalog to retrieve from
	dataset_time	A time string to select datasets active at a specific time

Returns:

IPA error status.

int ipa_get_assoc	(	IPAContext *	ipa,
		IPAAssoc *	assoc
	)

Retrieve the next range in an open dataset.

Parameters:

	ipa	A valid IPA context.
	assoc	(out) IPAAssoc record of the next range in the dataset.

Returns:

IPA error status.