3.1.4.5 EcRRegisterPushNotification Method (Opnum 4)

The EcRRegisterPushNotification method registers a callback address with the server for a Session Context. The server MAY<26> support the EcRRegisterPushNotification method.

The callback address is used to notify the client of pending events on the server. This call requires an active session context handle from the EcDoConnectEx method, as specified in section 3.1.4.1. The server MUST store the callback address and the opaque context data in the Session Context. To notify the client of pending events, the server sends a packet containing just the opaque context data to the callback address. The callback address specifies which network transport is to be used to send the data packet.

For more information about notification handling, see [MS-OXCNOTIF].

 long __stdcall EcRRegisterPushNotification(
      [in, out, ref] CXH * pcxh,
      [in] unsigned long iRpc,
      [in, size_is(cbContext)] unsigned char rgbContext[],
      [in] unsigned short cbContext,
      [in] unsigned long grbitAdviseBits,
      [in, size_is(cbCallbackAddress)] unsigned char rgbCallbackAddress[],
      [in] unsigned short cbCallbackAddress,
      [out] unsigned long *hNotification
 );

pcxh: A session context handle. On input, the client MUST pass a valid session context handle that was created by calling the EcDoConnectEx method. The server uses the session context handle to identify the Session Context to use for this call. On output, the server MUST return the same session context handle on success.

The server can destroy the session context handle by returning a zero for the pcxh parameter. Reasons for destroying the session context handle are implementation-dependent; following are examples of why the server might destroy the session context handle:

• The session context handle that was passed in is not valid.

• An attempt was made to access a mailbox that is in the process of being moved.

iRpc: The server MUST ignore this value. The client MUST pass a value of 0x00000000.

rgbContext: Opaque client-generated context data that is sent back to the client at the callback address, passed in the rgbCallbackAddress parameter, when the server notifies the client of pending event information. The server MUST save this data within the Session Context and use it when sending a notification to the client.

cbContext: The size of the opaque client context data that is passed in the rgbContext parameter. If the value of this parameter is larger than 0x00000010, the server MUST fail this call with error code ecTooBig.

grbitAdviseBits: This parameter MUST be set to 0xFFFFFFFF.

rgbCallbackAddress: The callback address for the server to use to notify the client of a pending event. The size of this data is in the cbCallbackAddress parameter.

The data contained in this parameter follows the format of a sockaddr structure. For information about the sockaddr structure, see [MSDN-SOCKADDR].

The server supports the address families AF_INET and AF_INET6 for a callback address that corresponds to the protocol sequence types that are specified in section 2.1.

If an address family is requested that is not supported, the server MUST return error code ecInvalidParam. If the address family is supported but the communications stack of the server does not support the address type, the server MUST return error code ecNotSupported.

cbCallbackAddress: The length of the callback address in the rgbCallbackAddress parameter. The size of this parameter depends on the address family being used. If this size does not correspond to the size of the sockaddr structure based on address family, the server MUST return error code ecInvalidParam.

hNotification: A handle to the notification callback. If the call completes successfully, the hNotification parameter contains a handle to the notification callback on the server.

Return Values: If the method succeeds, the return value is 0. If the method fails, the return value is an implementation-specific error code or one of the protocol-defined error codes listed in the following table.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol as specified in [MS-RPCE].