v1 to v2

Updating existing v1 code to the v2 API

Some libipmeta functions have retained the same name, but now take or return different arguments / types.

ipmeta_init: now takes a single parameter describing which data structure to use to store the ipmeta data. Must be one of the defined values for the ipmeta_ds_id enum (e.g. IPMETA_DS_PATRICIA or IPMETA_DS_BIGARRAY).

ipmeta_enable_provider: the set_default argument has been removed from the parameter list in v2, so simply remove the last argument from any existing calls of this function.

ipmeta_lookup: the provider argument (which was a pointer to a single ipmeta provider) has been replaced with a pointer to the top-level ipmeta_t instance. A new argument has also been added: provmask, which can be used to limit the ipmeta lookup to a specific set of providers. If set to zero, the lookup will be performed against all enabled providers for the ipmeta_t instance provided.

A mask may be constructed using the values defined for the ipmeta_provider_id_t type, but you must subtract one from the defined value before including it in the mask. For instance, to create a provmask that would limit the lookup to just Maxmind and Prefix2AS data, you would do something like:

uint32_t provmask = 0;

// v2.0 - 3.0 (NOTE THE '- 1' on each of these lines!):
provmask |= (1 << (IPMETA_PROVIDER_MAXMIND - 1));
provmask |= (1 << (IPMETA_PROVIDER_PFX2AS - 1));

// v3.1 or later:
provmask |= IPMETA_PROV_TO_MASK(IPMETA_PROVIDER_MAXMIND);
provmask |= IPMETA_PROV_TO_MASK(IPMETA_PROVIDER_PFX2AS);

ipmeta_lookup_single: the biggest change is that this function no longer returns a single ipmeta_record_t *, as there can now be multiple providers that return a result for a single IPv4 address. Instead, this method now returns an integer to indicate how many results there were (or -1 if the lookup resulted in an error for some reason), and takes an ipmeta_record_set_t * as a parameter which will be modified to contain the results from all desired providers.

Many of the other changes that affected ipmeta_lookup also apply here, so consult the entry for that function for more detail. These include:

• Taking an ipmeta_t * instance as a parameter rather than an ipmeta_provider_t *
• The addition of a provmask parameter to allow certain providers to be ignored when doing the lookup.

New methods

ipmeta_record_set_clear(ipmeta_record_set_t *this): allows a record set instance to be re-used, rather than having to free it and create a new one -- useful when you are doing a lot of non-simultaneous lookups.

ipmeta_dump_record_set_by_provider(ipmeta_record_set_t *this, char *ip_str, int providerid): behaves the same as ipmeta_dump_record_set() but only writes records that have come from a specific provider.

ipmeta_write_record_set_by_provider(ipmeta_record_set_t *this, iow_t *file, char *ip_str, int providerid): behaves the same as ipmeta_write_record_set() but only writes records that have come from a specific provider.

Removed methods

ipmeta_get_default_provider(): default provider no longer makes sense, as the default behaviour would now be to provide results from all providers.