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, char *uname)
 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.
int ipa_do_assoc_query (IPAContext *ipa, const char *catalog, const char *range, const char *label, const char *value, const char *t1, const char *t2, int displayfields)
 Get associations matching all of the supplied parameters.

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:


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.

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.

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,
char *  uname 
)

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
uname Username of the user in the IPA users table
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.
int ipa_do_assoc_query ( IPAContext ipa,
const char *  catalog,
const char *  range,
const char *  label,
const char *  value,
const char *  t1,
const char *  t2,
int  displayfields 
)

Get associations matching all of the supplied parameters.

Parameters:
ipa A valid IPA context.
catalog Catalog name
range IP range
label Comma-delimited list of one or more labels
value A number or number range in the form of x-y
t1 Begin date
t2 End date
displayfields Bitmask of columns to return from query
Returns:
IPA error status.