RpcBindingSetOption

The RpcBindingSetOption function enables client applications to specify message-queuing options on a binding handle. This function is supported only on Windows NT, version 4.0 with Service Pack 3, or later. Support for Windows 95 is available with the second release of DCOM 95. Windows 98 will support this function.

#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcBindingSetOption(
  RPC_BINDING_HANDLE  hBinding,  
  unsigned long  Option,      
  unsigned long  OptionValue  
);

Parameters

hBinding
The server binding to modify.
Option
The binding property to modify (see table in the Remarks section).
OptionValue
The new value for the binding property (see table in the Remarks section).

Return Values

Value Meaning
RPC_S_OK Success.
RPC_S_CANNOT_SUPPORT The function is not supported for either the operating system or the transport. Note that calling RpcBindingSetOption on binding handles that use any protocol sequence other than ncadg_mq will fail and return this value.

Remarks

RPC client processes use RpcBindingSetOption to control the delivery quality of service, call logging, and call lifetimes. Changing the binding-handle properties will affect all remote calls until the properties are changed by another call to RpcBindingSetOption. You can also call RpcBindingSetAuthInfo to set security options for the binding handle. The following table describes the possible options and their values for RpcBindingSetOption:

Option Option Value Description
RPC_C_OPT_MQ
_DELIVERY		 RPC_C_MQ_EXPRESS (The default value.) Remote calls to the server remain in active memory as they pass through the network.
RPC_C_MQ
_RECOVERABLE		 Remote calls to the server are stored on disk until they are delivered and executed. This guarantees delivery even if the server goes down.
RPC_C_OPT_MQ
_PRIORITY		 0-7 (The default is 3.) Calls with a higher priority number have precedence over calls with a lower priority number.
RPC_C_OPT_MQ
_JOURNAL		 RPC_C_MQ_JOURNAL
_NONE (The default value.)		 Calls are never logged.
RPC_C_MQ_JOURNAL
_DEADLETTER		 Calls are logged only when the message cannot be delivered. This can occur when the time specified in RPC_C_MQ_TIME_TO
_REACH_QUEUE or RPC_C_MQ_TIME_TO
_BE_RECEIVED expires before the message is delivered to the server, or the target queue no longer (of the server) no longer exists.
RPC_MQ_JOURNAL
_ALWAYS		 Calls are always logged at the originating machine.
RPC_C_OPT_MQ
_ACKNOWLEDGE		 FALSE (The default value.) Control returns to the client process immediately after the MSMQ transport receives the call.
TRUE The remote call does not return control to the client until it receives an acknowledgment that the call reached the server's receive queue.
RPC_C_OPT_MQ_TIME
_TO_REACH_QUEUE		 Time in seconds. The default value is INFINITE. The amount of time allowed for a call to reach the Queue Manager on the target system. If the call times out before reaching the target system, it is discarded.
RPC_C_OPT_MQ_TIME
_TO_BE_RECEIVED		 Time in seconds. The default value is INFINITE. The amount of time allowed for a call to reach the server process receive queue on the target system. If the call times out before the RPC server application receives it, it is discarded.

See Also

message, RPC Message Queuing, RpcBindingInqOption, RpcBindingSetAuthInfo, RpcBindingInqAuthClient