CeRapiInvoke

This function can be used as a general-purpose mechanism to remotely execute a routine on the Windows CE device.

HRESULT CeRapiInvoke( 
LPCWSTR pDllPath, 
LPCWSTR pFunctionName, 
DWORD cbInput, 
BYTE *pInput, 
DWORD *pcbOutput, 
BYTE **ppOutput, 
IRAPIStream **ppIRAPIStream, 
DWORD dwReserved);

Parameters

• pDllPath
  [in] Pointer to a buffer containing the name of a DLL on the Windows CE device containing pFunctionName.
• pFunctionName
  [in] Pointer to a buffer containing the name of the function that RAPI should call on the Windows CE device.
• cbInput
  [in] Number of bytes in the input buffer *pInput.
• pInput
  [in] Pointer to a buffer containing the input data.
• pcbOutput
  [out] Pointer to a variable that is set to the number of bytes in the output buffer ppOutput when the function returns.
• ppOutput
  [out] Pointer to a variable that is set to the location of the output buffer upon return.
• ppIRAPIStream
  [out] Pointer to a variable that is set to the address of the IRAPIStream interface.
• dwReserved
  Reserved.

Return Values

If RAPI services on the Windows CE device successfully locate and call the client function, then in Block Mode the return value is that which is returned on the Windows CE device by the called function. In Stream Mode the return value is S_OK. If the function was not called successfully, or an exception occurred during its execution, an error code is returned.

The CeGetLastError function can be used to get the error code, which takes the value set by pFunctionName, including the following values:

• ERROR_FILE_NOT_FOUND
  The LoadLibrary pDllPath call failed on the device.
• ERROR_CALL_NOT_IMPLEMENTED
  The GetProcAddress of pFunctionName call on the device failed.
• ERROR_EXCEPTION_IN_SERVICE
  An exception occurred during execution of pFunctionName.

Remarks

This function is a part of the remote application programming interface (RAPI), which invokes function calls on a Windows CE–based device. RAPI functions are supported only for applications that run on desktop platforms.

An application should allocate memory for the pInput parameter with the LocalAlloc function. The memory is freed by the system. The system allocates memory for the ppOutput parameter. When the application is completed with the buffer, it should free the memory with the LocalFree function.

The CeRapiInvoke function operates in either block mode or stream mode.

In block mode, the caller passes the data in a single buffer as an input parameter and receives the response in a single buffer as an output parameter. This is a synchronous call, thus all input or output data must be present in memory at the time of the call.

In stream mode, the CeRapiInvoke function returns a pointer to an IStream type interface that can be used to exchange arbitrary sized data in any order and direction. In this mode, the caller can still pass data in a single buffer as an input parameter, but from that point on all data should be exchanged by means of the stream. Thus the data can be read, written, and stored in chunks.

Streaming is significantly faster than block mode.

The ppIRAPIStream parameter specifies block mode or stream mode. Select block mode by supplying the value NULL. Select stream mode by supplying a valid pointer to a variable of type IRAPIStream; this IRAPIStream interface can be used for a direct transfer of data. If ppIRAPIStream is not NULL, the pFunctionName parameter on the Windows CE device will be passed a pointer to the IRAPIStream interface.

The IRAPIStream ** definition is based on IStream and has been expanded by two new methods to allow the setting of timeouts. These methods, IRAPIStream::SetRapiStat and IRAPIStream::GetRapiStat,are modeled ** after the IStream::Stat method.

Requirements

See Also

CeGetLastError, GetProcAddress, LoadLibrary, LocalAlloc, LocalFree, IRAPIStream, IRAPIStream::SetRapiStat, IStream::Stat

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.