Overview of RAPI Functions

< BACK  NEXT >

[oR]

Many of the RAPI functions are directly equivalent to their Windows CE counterparts and therefore do not warrant a detailed description. There are, however, some general points to remember when calling these functions:

• Use CeRapiGetError as described above to determine errors.

• Call CeCloseHandle to close handles returned from functions such as CeCreateProcess and CeCreateFile.

• Use CeFindClose to close a handle returned from CeFindFirstFile.

• Call CeRapiFreeBuffer to free buffers returned from CeReadRecordProps.

The following sections list the RAPI functions by group, together with a brief description of their purpose.

File and Folder Manipulation

RAPI provides a complete set of functions for manipulating files and folders on a connected Windows CE device. You can refer to Chapters 2 and 3 for information on the equivalent Windows CE functions.

Note that there is no equivalent Windows CE function for CeFindAllFiles this function is used to find matching files through a single function call rather than the multiple calls that CeFindFirstFile and CeFindNextFile require. This improves performance especially when using slow communications connections. Listing 10.2 shows a call to CeFindAllFiles to return all files in the root folder. The source code is located in \RAPI\FindAllFiles on the CDROM.

Table 10.2. File and Folder manipulation RAPI functions

Function	Purpose
CeOidGetInfoEx	Returns information about an object in the object store. This function can return information about database volumes.
CeOidGetInfo	Returns information about any object in an object store except databases in a database volume.
CeFindFirstFile	Finds first file that matches a file specification.
CeFindNextFile	Finds the next file.
CeFindClose	Closes the handle returned from CeFindFirstFile.
CeGetFileAttributes	Gets a file's attributes.
CeSetFileAttributes	Sets a file's attributes.
CeCreateFile	Opens a file on a Windows CE device.
CeReadFile	Reads from an open file.
CeWriteFile	Writes to an open file.
CeCloseHandle	Closes a file given the handle returned from CeCreateFile.
CeFindAllFiles	Returns information on all files that match a file specification. This function has no Windows CE or Win32 equivalent.
CeSetFilePointer	Moves current file pointer to specified location.
CeSetEndOfFile	Sets the End of File to the position of the current file point.
CeCreateDirectory	Creates a new folder.
CeRemoveDirectory	Removes specified folder.
CeMoveFile	Moves or renames a file.
CeCopyFile	Copies a file.
CeDeleteFile	Deletes a file.
CeGetFileSize	Gets the current size of a file.
CeGetFileTime	Gets date and time for last access and read and create times for a file.
CeSetFileTime	Sets date and time for last access and read and create times for a file.
CeGetTempPath	Returns the directory where temporary files should be located.

Listing 10.2 CeFindAllFiles call to list files in root folder

 int main(int argc, char* argv[]) {   HRESULT hr;   DWORD dwFileCount;   LPCE_FIND_DATA pFindDataArray;   char szFilename[MAX_PATH];   // List files in root directory of connected CE Device   hr = CeRapiInit();   if(FAILED(hr))   {     cout   "Could not initialize RAPI:"            GetLastError()   endl;     return 1;   }   if(!CeFindAllFiles(L"\\*.*",       FAF_NAME | FAF_SIZE_LOW | FAF_ATTRIBUTES,       &dwFileCount,       &pFindDataArray))     ShowRAPIError();   else   {     cout   "Files in root of Windows Device:"            endl;     for(DWORD i = 0; i < dwFileCount; i++)     {       wcstombs(szFilename,         pFindDataArray[i].cFileName,         MAX_PATH);       cout   szFilename  "";       if(pFindDataArray[i].dwFileAttributes           & FILE_ATTRIBUTE_DIRECTORY)         cout   "<DIR>"   endl;       else         cout            pFindDataArray[i].nFileSizeLow             endl;     }     CeRapiFreeBuffer(pFindDataArray);   }   hr = CeRapiUninit();   if(FAILED(hr))     cout   "Could not un-initialize RAPI"   endl;   return 0; } 

The code in Listing 10.2 calls CeRapiInit, so the application will wait until a device is connected. A call is then made to CeFindAllFiles with flags requesting that the file name, size, and attributes be returned (Table 10.3). Notice that only the low DWORD is returned for the file size (FAF_SIZE_LOW), and this assumes that all files on the Windows CE device are less than 4 GB.

The following flags can be passed to dwFlags and combined where applicable:

• FAF_ATTRIB_CHILDRED Return only directories that have child items.

• FAF_ATTRIB_NO_HIDDEN Do not return hidden files or directories.

Table 10.3. CeFindAllFiles Returns information on files matching a file specification

CeFindAllFiles
LPCWSTR szPath	File specification, including path information.
DWORD dwFlags	Flags specifying what to return and special search options.
LPDWORD lpdwFoundCount	Pointer to a DWORD in which the number of files is returned.
LPLPCE_FIND_DATA ppFindDataArray	Pointer to a pointer to a LPCE_FIND_DATA structure. The returned pointer references the information on the files that matched the search.
BOOL Return Value	TRUE for success, FALSE for failure.

• FAF_FOLDERS_ONLY Only return folders, not files.

• FAF_NO_HIDDEN_SYS_ROMMODULES Do not return files in ROM.

• FAF_ATTRIBUTES Return file attributes.

• FAF_CREATION_TIME Return file creation time.

• FAF_LASTACCESS_TIME Return file last access time.

• FAF_LASTWRITE_TIME Return the file last write time.

• FAF_SIZE_HIGH Return the high DWORD of the file size.

• FAF_SIZE_LOW Return the low DWORD of the file size.

• FAF_OID Return the OID of the file.

• FAF_NAME Return the file name.

The CeFindAllFiles function returns a pointer to a buffer that contains a CE_FIND_DATA array for each file that matches the file specification. This buffer is owned by Windows and must be freed by calling the function CeRapiFreeBuffer. The CE_FIND_DATA structure contains members for each data item that can be returned for a file.

 typedef struct _CE_FIND_DATA {   DWORD    dwFileAttributes;   FILETIME ftCreationTime;   FILETIME ftLastAccessTime;   FILETIME ftLastWriteTime;   DWORD    nFileSizeHigh;   DWORD    nFileSizeLow;   DWORD    dwOID;   WCHAR    cFileName[MAX_PATH]; } CE_FIND_DATA, *LPCE_FIND_DATA; 

Property Database RAPI Functions

The functions shown in Table 10.4 can be used to manipulate property databases on a connected Windows CE device. You can refer to Chapter 4 for details on the Windows CE function equivalents. The function CeFindAllDatabases does not have a Windows CE equivalent it is used to return information on all databases that match a specification. As with CeFindAllFiles, this function is used to improve performance. Note that CeFindAllDatabases does not return information on databases in volumes. The function CeFindFirstDatabaseEx should be used to search database volumes. You should try to limit the number of calls to CeWriteRecordProps and CeReadRecordProps to improve performance by reading or writing as many properties at a time as possible.

Table 10.4. Property database RAPI functions

Function	Purpose
CeMountDBVol	Mounts a database volume.
CeUnmountDBVol	Unmounts a database volume.
CeFlushDBVol	Flushes database changes out to storage.
CeCreateDatabase	Creates a new database in the object store.
CeCreateDatabaseEx	Creates a new database in a mounted database volume.
CeDeleteDatabase	Deletes a database.
CeDeleteRecord	Deletes a record.
CeFindFirstDatabase	Finds first database that matches a specification.
CeFindNextDatabase	Finds next database using handle returned from CeFind-FirstDatabase.
CeOpenDatabase	Opens a database in the object store.
CeOpenDatabaseEx	Opens a database in a mounted volume.
CeReadRecordProps	Reads properties from a record. Use CeRapiFreeBuffer to free the returned buffer.
CeSeekDatabase	Locates a record in the database.
CeSetDatabaseInfo	Sets database information, such as name or sort orders.
CeSetDatabaseInfoEx	Sets database information for a database in a mounted database volume.
CeWriteRecordProps	Writes property values to a database.
CeFindAllDatabases	Returns information on all databases that match a specification.

Registry RAPI Functions

The functions in Table 10.5 can be used to manipulate keys in the Windows CE device's registry. The Windows CE equivalent functions are described in Chapter 4.

Table 10.5. Registry RAPI functions

Function	Purpose
CeRegOpenKeyEx	Opens a key
CeRegEnumKeyEx	Enumerates sub-keys of an open key
CeRegCreateKeyEx	Creates a new key, or opens an existing key
CeRegCloseKey	Closes an open key
CeRegDeleteKey	Deletes a key
CeRegEnumValue	Enumerates values for a key
CeRegDeleteValue	Deletes a value from a key
CeRegQueryInfoKey	Returns information about an open key
CeRegQueryValueEx	Retrieves type and data for a value name for an open key
CeRegSetValueEx	Sets data into a value for an open key

The code in Listing 10.3 shows how to use the RAPI registry functions to obtain the device name for the connected Windows CE device. This is the name that is configured through the Control Panel's Communication applet. This information is located in HKEY_LOCAL_MACHINE\Ident\Name. You can also find the Description ("Desc" value) and original device name ("OrigName" value) from this registry key. Information about the type of device and manufacturer can be found in the HKEY_LOCAL_MACHINE\Platform key. Registry functions are described in more detail in Chapter 4.

Listing 10.3 Determining device name of connected device

 #include "stdafx.h" #include <rapi.h> #include <iostream.h> BOOL CeGetPlatformName(LPTSTR pszPlatformName) {   BOOL     fSuccess  = FALSE;   LONG     nRetVal   = 0;   HKEY     hkey      = NULL;   DWORD    dwType    = 0;   DWORD    cbSize    = 0;   WCHAR    szPlatformNameW[MAX_PATH];   nRetVal = CeRegOpenKeyEx( HKEY_LOCAL_MACHINE,     L"Ident", 0, KEY_ALL_ACCESS, &hkey);   if (ERROR_SUCCESS == nRetVal && hkey)   {     // get the registry value     cbSize = sizeof(szPlatformNameW);     nRetVal = CeRegQueryValueEx( hkey,         "NAME", 0, &dwType,         LPBYTE)szPlatformNameW, &cbSize);     if (ERROR_SUCCESS == nRetVal)     {       szPlatformNameW[cbSize / sizeof(WCHAR)] = '\0';       if (wcstombs( pszPlatformName,           szPlatformNameW, MAX_PATH))         fSuccess = TRUE;     }   }   if (hkey)     CeRegCloseKey( hkey );   return fSuccess; } int main(int argc, char* argv[]) {   HRESULT hr;   char szDeviceName[MAX_PATH];   // List files in root directory of connected CE Device   hr = CeRapiInit();   if(FAILED(hr))   {     cout   "Could not initialize RAPI:"            GetLastError()   endl;     return 1;   }   if(CeGetPlatformName(szDeviceName))     cout   "Device Name: "   szDeviceName   endl;   else     cout   "Could not retrieve device name"   endl;   hr = CeRapiUninit();   if(FAILED(hr))     cout   "Could not un-initialize RAPI"   endl;   return 0; } 

The code in the CeGetPlatformName function is straightforward registry code. However, it is important to remember that all key and value names must be specified as Unicode strings. Further, the returned strings (for example, the device name) will be Unicode, and may need to be converted to ANSI character strings.

System Information RAPI Functions

Table 10.6 lists RAPI functions used to obtain information about the Windows CE devices.

Table 10.6. System Information RAPI functions

Function	Purpose
CeGetStoreInformation	Returns information about the state of the object store in a STORE_INFORMATION structure
CeGetSystemMetrics	Gets information about the Windows CE device, such as size of user interface elements like scrollbars
CeGetDesktopDeviceCaps	Returns information about the capabilities of the display, such as the number of display colors
CeGetSystemInfo	Fills a SYSTEM_INFO structure with information about the device, such as the type of processor, page file size, and address space
CeCheckPassword	Allows a string to be compared with the current password on the Windows CE device
CeGetVersionEx	Fills a CEOSVERSIONINFO structure with details about the operating system version and platform identifier
CeGlobalMemoryStatus	Returns information about the physical and virtual memory status
CeGetSystemPowerStatusEx	Fills a SYSTEM_POWER_STATUS_EX structure with data about battery and other power information

Miscellaneous RAPI Functions

Finally, Table 10.7 lists RAPI functions that allow access to errors, create processes, obtain information about windows, and interact with the shell.

Table 10.7. Miscellaneous RAPI functions

Function	Purpose
CeGetLastError	Returns error value from last RAPI function call
CeCreateProcess	Creates a new process on a connected device
CeGetWindow	Obtains a window handle
CeGetWindowLong	Returns information about the specified window, returned as a long value
CeGetWindowText	Gets window text associated with a window handle
CeGetClassName	Gets the class name associated with a window handle
CeGetSpecialFolderPath	Gets pathname for the location of special folders, such as desktop, "My Documents," and favorites
CeSHCreateShortcut	Creates a shortcut file
CeSHGetShortcutTarget	Gets information about a shortcut file

< BACK  NEXT >