25.3.1. Чтение определенной записи

25.3.1. Чтение определенной записи

Функции dpget() и dpgetwb() производят поиск записей в базе данных по ключу.

int dpget(DEPOT * depot, const char * key, int keySize, int start,

 int max, int * dataSize);

key является элементом (ключом), с помощью которого производится поиск по базе данных, a keySize определяет длину ключа (или значение -1, при котором Depot использует функцию strlen(key) для определения длины ключа). С помощью следующих двух параметров, start и max, можно производить частичное чтение записей; параметр start задает смещение в данных, с которого начнется операция чтения, а max — максимальное количество байтов для чтения. Например, если область данных представляла бы собой массив из четырехбайтовых целочисленных значений int, то в результате присвоения параметру start значения 12 и параметру max значения 8 производилось бы чтение четвертого и пятого элементов массива. Если для чтения доступно менее start байтов, функция dpget() вернет NULL. Чтобы прочитать все байты из данных, параметру max следует присвоить значение -1.

Если последний параметр, dataSize, не будет равен NULL, то целое число, на которое он указывает, будет соответствовать количеству прочитанных байтов.

В случае сбоя эта функция возвращает NULL, а в случае успешного завершения она возвращает указатель на прочитанные данные. В случае сбоя dpcode сообщает о том, что стало причиной сбоя. В частности, если элемент не существует или имеет менее start байтов данных, dpcode будет присвоено DP_ENOITEM.

Когда функция dpget() возвращает данные, к ним добавляется байт 0, позволяя работать с ними как со строкой. Размещение указателя производится с помощью функции malloc(), и приложение отвечает за освобождение памяти после завершения своей работы. Если приложениям необходимо поместить данные в буфер, вместо того чтобы Depot размещала его с помощью функции malloc(), то они должны использовать функцию dpgetwb().

int dpgetwb(DEPOT * depot, const char * key, int keySize, int start,

int max, const char * data);

Функции dpgetwb() и dpget() отличаются друг от друга только двумя параметрами: max (который интерпретируется по-разному) и data (который заменяет параметр dataSize из функции dpgetwb()). Параметр data должен указывать на буфер из max байтов, в который функция dpgetwb() будет помещать данные, прочитанные из базы данных. В функции dpgetwb() параметр max не должен иметь значение -1, и буфер не будет иметь байт 0, автоматически добавляемый в него этой функцией. Функция dpgetwb() возвращает количество байтов, хранящихся в data, и -1, если запись не была найдена, если данных оказалось меньше start байтов или если возникла ошибка.