|
Данный документ соответствует geoip C API версии 1.0.2 от 20 августа 2007.
|
 |
 |
Geoip C API
Данное API реализовано на языке C. Компиляция исходного кода и работоспособность были проверены с помощью компилятора gcc (версий с 2.95 по 4.1 включительно) на системах FreeBSD (версий с 4.8 по 6.2 включительно) и Linux (версий с 2.4.9 по 2.6.20 включительно). Для компиляции и использования API не требуется дополнительных заголовочных файлов и библиотек (за исключением стандартных, входящих в поставку операционных систем и компилятора).
Использование API
Работа с API выполняется в четыре этапа:
- создание сессии (соединения) с сервером geoip;
- отправка запроса серверу;
- высвобождение полученных данных;
- высвобождение объекта сессии.
Создание сессии
Функция
geoConnect – устанавливает соединение с сервером IP географии.
Обзор
#include "geoip-client.h"
struct GeoSession *geoConnect(const char *host, int port);
Описание
Параметр host указывает адрес сервера IP географии в строковом представлении, а port значение порта на котором сервер принимает запросы.
Возвращаемое значение
Функция всегда возвращает структуру данных типа GeoSession. Если соединение произошло успешно, то параметр структуры fd будет отличным от значения -1, а параметр statusMsg равным 0. Обзор структуры GeoSession:
struct GeoSession {
int fd;
int http;
char *statusMsg;
};
Ошибки
В случае ошибки при установлении соединения с сервером IP географии, в возвращаемой структуре GeoSession параметр fd будет равен -1, а параметр statusMsg будет содержать описание причины по которой не удалось установить соединение, в формате C строки. В случае ошибки необходимо перейти к пункту «2.4 – высвобождение объекта сессии» для высвобождения ресурсов использованных структурой GeoSession.
Отправка запроса серверу
Функция
geoLocate – отправляет запрос серверу IP географии.
Обзор
#include "geoip-client.h"
struct GeoData *geoLocate(struct GeoSession *, const char *login,
const char *password, const char *ip, int format);
Описание
Первым аргументом является структура GeoSession созданная при помощи функции geoConnect. Аргументы login и password являются парой логин и пароль, для доступа к серверу, полученные через web интерфейс. Параметр ip передаётся в строковом представлении в формате C строки. Аргумент format отвечает за представление данных в ответе со стороны сервера и имеет следующие предопределённые константы для использования в качестве значения:
static const int geoLocateFormatDEFAULT = 0;
static const int geoLocateFormatShort = 1;
static const int geoLocateFormatLong = 2;
Первая константа (geoLocateFormatDEFAULT) полагается на формат данных возвращаемый сервером по умолчанию. Вторая (geoLocateFormatShort) возвращает данные в т. н. сокращённом формате: все данные латинскими символами, наименование страны сокращено до двух символьного кода по стандарту ISO, а регионы и города без пробелов между словами. При использовании последней константы (geoLocateFormatLong) данные будут возвращены в полном объёме в виде удобном для чтения человеком, при этом названия Российских и Украинских населённых пунктов будут переданы кириллицей в кодировке windows-1251, а зарубежных – латиницей.
Возвращаемое значение
При успешной отправке запроса, возвращается структура GeoData содержащая данные географии о запрошенном IP адресе. Обзор структуры GeoData:
struct GeoData {
char *country;
char *region;
char *state;
char *city;
float latitude;
float longitude;
};
Параметры структуры country, region, state и city содержат информацию о местоположении запрошенного IP адреса. Параметры latitude и longitude географические координаты. База данных по определённым IP адресам может быть не полной. В таких случаях, поля структуры GeoData, информация по которым отсутствует, будут равны нулю.
Возвращённое значение необходимо высвободить при помощи функции geoFreeGeoData (см. пункт «2.3 Высвобождение полученных данных»).
Ошибки
В случае ошибки при взаимодействии с сервером IP географии, в передаваемой структуре GeoSession параметр fd будет равен -1, а параметр statusMsg будет содержать описание причины по которой не удалось установить соединение, в формате C строки. Следует так же проверять параметр http структуры GeoSession. Если он равен 403, то возможно переданы не верная пара login и password или исчерпано ограничение на количество запросов в единицу времени. Значение 400 свидетельствует о том, что параметр ip передан в неверном формате.
Высвобождение полученных данных
Функция
geoFreeGeoData – функция высвобождения памяти используемой структурой GeoData.
Обзор
#include "geoip-client.h"
void geoFreeGeoData(struct GeoData *);
Описание
После работы со структурой GeoData необходимо освободить память при помощи функции geoFreeGeoData. Функция освобождает как адресное пространство занимаемое самой структурой, так и данными на которые ссылаются её указатели.
Высвобождение данных сессии
Функция
geoFreeGeoSession – функция высвобождения ресурсов использованных для установки соединения с сервером IP географии.
Обзор
#include "geoip-client.h"
void geoFreeGeoSession(struct GeoSession *);
Описание
По окончанию работы с сервером (отправки запроса, или ошибки при установлении соединения) необходимо высвободить ресурсы использованные для создания сессии. Функция geoFreeGeoSession высвобождает использованные ресурсы, память занятую структурой, а так же данными на которые ссылаются её указатели.
|
