Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method can be used as a general-purpose mechanism to remotely execute a routine on a remote Windows Embedded CE-based device.

Syntax

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

Parameters

pDllPath

[in] Pointer to a string buffer containing the name of a DLL that is on the Windows Embedded CE-based device and that contains the function identified in pFunctionName.

pFunctionName

[in] Pointer to a string buffer containing the name of the function that RAPI2 should call on the Windows Embedded CE-based 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 ppOutputwhen the function returns.

ppOutput

[out] Pointer to a variable that is set to the location of the output buffer upon return.

ppIRAPIStream

[in, out] The ppIRAPIStreamparameter 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 IRAPIStreaminterface can be used for a direct transfer of data. If ppIRAPIStreamis not NULL, the pFunctionNameparameter on the Windows Embedded CE-based device will be passed a pointer to the IRAPIStreaminterface.

dwReserved

Reserved.

Return Value

If RAPI2 services on the Windows Embedded CE-based device successfully locate and call the client function, then in Block Mode the return value is that which is returned on the Windows Embedded CE-based 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 IRAPISession::CeGetLastErrorfunction can be used to get the error code, which takes the value set by pFunctionName,including the following values:

HRESULT_FROM_WIN32(ERROR_MOD_NOT_FOUND)

The LoadLibrary pDllPathcall failed on the device.

HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)

The GetProcAddressof pFunctionNamecall on the device failed.

HRESULT_FROM_WIN32(ERROR_EXCEPTION_IN_SERVICE)

An exception occurred during execution of pFunctionName.

Remarks

IRAPISession::CeRapiInvokeloads the device-side DLL named in pDllPath, then calls the RAPI extension named in pFunctionName. It is the responsibility of the RAPI extension to release the IRAPIStream object (that is, to call pIRAPIStream->Release();).

An application should allocate memory for the pInputparameter with the LocalAllocfunction. The caller is responsible for freeing pInput. The system allocates memory for the ppOutputparameter. When the application is completed with the buffer, it should free the memory with the LocalFreefunction.

The IRAPISession::CeRapiInvokefunction 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 IRAPISession::CeRapiInvokefunction returns a pointer to an IStreamtype 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 ppIRAPIStreamparameter 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 IRAPIStreaminterface can be used for a direct transfer of data. If ppIRAPIStreamis not NULL, the pFunctionNameparameter on the Windows Embedded CE device will be passed a pointer to the IRAPIStreaminterface.

The IRAPIStreamdefinition is based on IStreamand has been expanded by two new methods to allow the setting of timeouts. These methods, IRAPIStream::SetRapiStatand IRAPIStream::GetRapiStat, are modeledafter the IStream::Statmethod.

The IRAPIStreamobject does not guarantee the reception of data by the device. It is up to your application to implement application-level ACK. The device application should send an acknowledgement code after it has succeeded in reading all of the data from the stream. After the desktop application has written to the stream, it should wait until it receives the acknowledgement code from the device application before it releases the stream.

Note:
In previous releases, this method could be used to obtain a handle to objects on the remote device that could be used by other RAPI method calls, such as CeWriteRecordProps. Starting with Windows CE 5.0, RAPI method calls will fail if a handle retrieved by this method is used. Database and registry key handles should be obtained by using the CeOpenDatabaseExand CeRegOpenKeyExRAPI methods.

Requirements

Header rapi2.h
Library ole32.lib, rapiuuid.lib
Windows Embedded CE Windows Embedded CE 6.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also