DlpReadRecordByID(3)

NAME
DlpReadRecordByID, DlpReadNextModifiedRec, DlpReadRecordByIndex, DlpReadNextRecInCategory, DlpReadNextModifiedRecInCategory - read a record from a PalmOS 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_PConnection(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 retrieve. Record indices begin at 0. recinfo, as with DlpReadRecordByID(), will be filled in with the record header.

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 category 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), DlpReadRecordIDList(3), DlpResetRecordIndex(3).