dlpreadrecordbyid(3)

NAME

DlpReadRecordByID, DlpReadNextModifiedRec,

DlpReadRecordByIndex

DlpReadNextModifiedRecInCategory

device

LIBRARY

libpconn

SYNOPSIS

#include <palm.h>
#include <pconn/pconn.h>
int
DlpReadRecordByID(PConnection  *pconn,  const  ubyte handle,
const udword id, const uword  offset,  const  uword  len,  struct
dlp_recinfo *recinfo, const ubyte **data);
int
DlpReadRecordByIndex(PConnection *pconn, const ubyte handle,
const uword index, struct dlp_recinfo *recinfo);
int
DlpReadNextModifiedRec(PConnection   *pconn,   const   ubyte
handle, struct dlp_recinfo *recinfo, const ubyte **data);
int
DlpReadNextRecInCategory(PConnection   *pconn,  const  ubyte
handle, const ubyte category, struct dlp_recinfo *recinfo,  const
ubyte **data);
int
DlpReadNextModifiedRecInCategory(PConnection  *pconn,  const
ubyte handle, const ubyte category, struct dlp_recinfo  *recinfo,
const ubyte **data);

DESCRIPTION

These functions read a record from the Palm. In all of these

functions, pconn is the Palm connection, as returned by new_PCon

nection(3). handle is a database handle, as returned by

DlpOpenDB(3).

If a record has been deleted and expunged (i.e., when the

record was deleted and the ``Save archive copy on PC'' checkbox

was unchecked), the length of the record's data will be given as

0, and data will point to an empty string.

DlpReadRecordByID is the preferred way of reading a record

from the Palm.

id specifies the identifier of the record to be retrieved;

this identifier is usually gotten with DlpReadRecordIDList().

offset is the offset at which to begin reading the record:

to read the record from the beginning, use 0; to skip the first

10 bytes, use 10.

len specifies the maximum number of bytes to read.

recinfo will be filled with the record header, which has the

following form:

struct dlp_recinfo
{

udword id;
uword index;
uword size;
ubyte attributes;
ubyte category;

};

data will be filled in with a pointer to the record data.

This pointer is to an internal buffer, and must not be freed. The

length of the data will be the smaller of recinfo.size and len.

DlpReadRecordByIndex is less useful than it might seem. It

reads the header of the indexth record, but not the record data.

Thus, if you only want to read the twelfth record in a database

and nothing else, you can use DlpReadRecordByIndex() to get the

index of the twelfth record, then use DlpReadRecordByID() to read

the record's data.

index specifies the index of the record whose header to re

trieve. Record indices begin at 0. recinfo, as with

DlpReadRecordByID

DlpReadNextModifiedRec reads the next record in the database

that has been modified since the last sync (or, more accurately,

since the modification flags were reset by DlpResetSyncFlags(3)

). Modified records include those whose contents have changed;

those that have been moved to a different category; and those

that have been deleted, with or without an archive copy.

handle, recinfo, and data are as for DlpReadRecordByID().

DlpReadNextRecInCategory reads the next record in the given

category.

category specifies the index of the category, in the range

0-15, with 0 being reserved for the ``Unused'' category. The cat

egory ID can be gotten from the category list at the start of the

AppInfo block. Sadly, although the category list is in a standard

format, libpconn does not include a facility for parsing it.

recinfo and data are as for DlpReadRecordByID().

DlpReadNextModifiedRecInCategory reads the next modified

record in the given category. All arguments are as for

DlpReadNextRecInCategory

RETURN VALUE

All of these functions return 0 if successful, or a negative

value otherwise.

SEE ALSO

libpconn(3), new_PConnection(3), DlpOpenDB(3), DlpReadRecor

dIDList(3), DlpResetRecordIndex(3).

BSD Aug 16, 2001

BSD