IDirectPlay4::SendEx

IDirectPlay4 Interface

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 timeout of a message.

Syntax

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 zero 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 non-zero priority will return a DPERR_UNSUPPORTED error. Call GetCaps to determine is this option is supported or not.

dwTimeout
Optional application-supplied timeout, 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 timeout should be used.

Note: Not all service providers support this option. If it is not supported, specifying a non-zero timeout 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 Value

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:
DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_INVALIDPRIORITY
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG
DPERR_UNSUPPORTED

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 non-zero priority and the service provider does not support priorities, or if you specify a non-zero timeout 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 timeout. 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.

See Also

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

Top of Page Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.