IDirectPlay4::SendEx

The IDirectPlay4::SendEx method sends a message to another player, to a group of players, or to all players in the session. SendEx is an enhanced version of the Send method and has more options available. SendEx supports both guaranteed and nonguaranteed messages. It also enables you to send asynchronous messages and to set the priority and time-out of a message.

HRESULT SendEx(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwPriority,
  DWORD dwTimeout,
  LPVOID lpContext,
  LPDWORD lpdwMsgID
);

Parameters

idFrom

ID of the sending player. The player ID must correspond to one of the local players on the computer from which the message is sent.

idTo

The destination ID of the message. To send a message to another player, specify the ID of the player. To send a message to all the players in a group, specify the ID of the group. To send a message to all the players in the session, use the constant symbol DPID_ALLPLAYERS. To send a message to the server player, specify the constant symbol DPID_SERVERPLAYER. A player cannot send a message to himself or herself.

dwFlags

Indicates how the message should be sent. By default (dwFlags = 0), the message is sent nonguaranteed.

DPSEND_ASYNC

Sends the message asynchronously. The function returns immediately and fills in the lpdwMsgID parameter. If this flag is not specified, the function does not return until the message has been sent (and acknowledged, if sent guaranteed). A DPMSG_SENDCOMPLETE system message is posted when the send has completed.

When this flag is used, the return value will be DPERR_PENDING if the message is put in the send queue. This is not a fatal error, but just a return value that lets you know the message did not get sent immediately.

DPSEND_ENCRYPTED

Sends the messages encrypted. This can only be done in a secure session. This flag can only be used if the DPSEND_GUARANTEED flag is also set. The message will be sent as a DPMSG_SECUREMESSAGE system message.

DPSEND_GUARANTEED

Sends the message by using a guaranteed method of delivery if it is available.

DPSEND_NOSENDCOMPLETEMSG

If this flag is set, no completion message is posted. This flag can only be used if the DPSEND_ASYNC flag is also set.

DPSEND_SIGNED

Sends the message with a digital signature. This can only be done in a secure session. This flag can only be used if the DPSEND_GUARANTEED flag is also set. The message will be sent as a DPMSG_SECUREMESSAGE system message.

lpData

Pointer to the data being sent.

dwDataSize

Length of the data being sent.

dwPriority

Priority of the message in the range from 0 to 65535. Zero is the lowest priority message. A larger number indicates a message with a higher priority. A message with a given priority will only be sent when there are no messages in the queue with a higher priority.

Note  Not all service providers support this option. If it is not supported, specifying a nonzero priority will return a DPERR_UNSUPPORTED error. Call GetCaps to determine is this option is supported or not.

dwTimeout

Optional application-supplied time-out, in milliseconds, that specifies a time limit for delivering the message. If the message cannot be delivered within this time, it is automatically canceled and a DPMSG_SENDCOMPLETE message is posted. Zero indicates that no time-out should be used.

Note  Not all service providers support this option. If it is not supported, specifying a nonzero time-out will return a DPERR_UNSUPPORTED error. Call GetCaps to determine is this option is supported or not.

lpContext

An application-defined context that is returned to the application as part of the completion message when the send has been completed. Can be NULL.

lpdwMsgID

Pointer to a DWORD that will be filled in with a DirectPlay-generated ID for the message. Use this ID to check the status of the message or to cancel it. Pass NULL if no message ID is needed. This parameter is only returned for asynchronous messages.

Return Values

For synchronous messages, returns DP_OK if successful. For asynchronous messages, returns DPERR_PENDING if the send reaches the point where it is successfully queued. You will then get the completion status from the DPMSG_SENDCOMPLETE message. Otherwise, returns one of the following error values:

This method returns DPERR_INVALIDPARAMS if the encrypted or signed flag is specified for a message that is not also specified as guaranteed, or if the DPSEND_NOCOMPLETEMSG flag is specified for a message that is not asynchronous. It returns DPERR_INVALIDPRIORITY if the priority value is not between 0 and 65535. It returns DPERR_NOTSUPPORTED if you specify a nonzero priority and the service provider does not support priorities, or if you specify a nonzero time-out and the service provider does not support this option.

Remarks

If the DirectPlay Protocol was specified in the session description (by setting the DPSESSION_DIRECTPLAYPROTOCOL flag in the DPSESSIONDESC2 structure), then all the options on SendEx are available. Otherwise, an application should call GetCaps to determine what options the service provider has implemented. SendEx supports guaranteed and nonguaranteed messages. Messages sent guaranteed will not be blocked if there are pending messages waiting to be acknowledged by the receiver.

If a message is sent asynchronously (by setting the DPSEND_ASYNC flag), the message will be put into a send queue and the SendEx function will return immediately. A system message (DPMSG_SENDCOMPLETE) will be posted to the receive queue of the sending player indicating the result of the send.

You can give messages priorities. A message is sent when there are no higher priority messages waiting to be sent and when there is available bandwidth.

You can give a message a time-out. If DirectPlay cannot deliver the message in the time specified, it will be canceled.

The DPSEND_SIGNED and DPSEND_ENCRYPTED flags cannot be used if the order of delivery of guaranteed messages is not preserved because the DPSESSION_NOPRESERVEORDER flag is set in the session description (DPSESSIONDESC2).

If messages are sent using different priorities, signing and encryption may not work. It is best for the application to decide on one priority level for secure messages and only use the security flag on that priority level. This is because validation of secure messages depends on the order in which they are received and prioritization may change this order.

If the DirectPlay Protocol is active, it will attempt to throttle outbound network traffic. That is, it will not always send packets as fast as possible. It will send packets as fast as it can without overwhelming the inbound bandwidth of the receiving computer.

System messages are always sent guaranteed, whether or not the service provider natively supports guaranteed messages, and whether or not you set the DirectPlay protocol flag. The DirectPlay protocol will be used automatically to send system messages guaranteed.

For non-system messages, if an application sets the DirectPlay protocol flag and sends a message guaranteed (by setting the DPSEND_GUARANTEED flag), the message will be sent guaranteed whether the service provider supports guaranteed messages or not.

For non-system messages, if an application does not set the DirectPlay protocol flag and sends a message guaranteed, the message will be sent guaranteed only if the service provider supports it. If the service provider does not support guaranteed messages, the message will not be sent guaranteed, regardless of the DPSEND_GUARANTEED flag.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dplay.h.
  Import Library: Use dplayx.lib.

See Also

IDirectPlay4::Send, IDirectPlay4::CancelMessage, IDirectPlay4::CancelPriority, IDirectPlay4::GetMessageQueue, DPMSG_SENDCOMPLETE