Palm OS Programming, 2nd Edition

Conduit Entry Points

In our initial discussion of conduits, we told you that a conduit has three required entry points. There are also some optional ones (including some that are only for CDK 3.0 or later). Now it is time to look at these entry points in greater detail.

Required Entry Points

The required entry points are as follows:

long GetConduitName(char* pszName, WORD nLen)

This function returns the conduit’s name in pszName. The length of the passed-in buffer is the second parameter. A conduit should truncate the conduit’s name, if needed, rather than writing past the end of the buffer.

Like all the entry points, the return value is 0 for no error, or nonzero for an error.

DWORD GetConduitVersion( )

This function returns the version of the conduit as a 4-byte value. The minor version is in the low byte. The major version is in the next byte. The upper two bytes are unused. A conduit with version 1.5 would return 0x15.

long OpenConduit(PROGRESSFN progress, CSyncProperties &sync)

It is from this entry point that the conduit actually does its syncing. The first parameter, progress, is a pointer to a function. Although most conduits don’t use this function, you can call it with a status string to display that status in the HotSync Progress dialog box. The second parameter is a structure with information about the sync. The most important fields in the structure are shown in Table 14-1.

Table 14-1. Important fields in CSyncProperties

Field	What it does
m_SyncType	An enumeration ...