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. |
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.
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.
IPA applications are responsible for transactional integrity. IPA provides methods for applications to begin, commit, and rollback (abort) transactions.
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.
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.
Users who are familiar with the IPA data model may wish to execute custom queries. To do so, follow this example:
enum IPAStatus |
The following error return values are defined for IPA:
enum IPACatalogType |
enum IPAContextState |
int ipa_create_context | ( | IPAContext ** | ipa, | |
char * | db_uri, | |||
char * | uname | |||
) |
Create a handle to an IPA data store.
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 |
void ipa_destroy_context | ( | IPAContext ** | ipa | ) |
Destroy an IPA context that was created with ipa_create_context().
ipa | The address of an IPAContext pointer. |
void ipa_begin | ( | IPAContext * | ipa | ) |
Begin an IPA transaction.
ipa | A valid IPA context. |
void ipa_commit | ( | IPAContext * | ipa | ) |
Commit (complete) an IPA transaction.
ipa | A valid IPA context. |
void ipa_rollback | ( | IPAContext * | ipa | ) |
Rollback (abort) an IPA transaction.
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.
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. |
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.
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. |
int ipa_add_cidr | ( | IPAContext * | ipa, | |
uint32_t | addr, | |||
uint32_t | prefix, | |||
char * | label, | |||
uint64_t | value | |||
) |
Convenience function for adding CIDRized IP ranges.
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. |
int ipa_get_dataset | ( | IPAContext * | ipa, | |
const char * | catalog_name, | |||
const char * | dataset_time | |||
) |
Retrieve a dataset record.
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 |
int ipa_get_assoc | ( | IPAContext * | ipa, | |
IPAAssoc * | assoc | |||
) |
Retrieve the next range in an open dataset.
ipa | A valid IPA context. | |
assoc | (out) IPAAssoc record of the next range in the 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.
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 |