DirectPlay4.SendEx

The DirectPlay4.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 DirectPlay4.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.

object.SendEx(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPSENDFLAGS, _
    msg As DirectPlayMessage, _
    priority As Long, _
    timeOut As Long, _
    context As Long) As Long

Parameters

object

Object expression that resolves to a DirectPlay4 object.

fromPlayerId

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.

toPlayerId

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 DPID_ALLPLAYERS. To send a message to the server player, specify the constant DPID_SERVERPLAYER. A player cannot send a message to itself.

flags

Flags from the CONST_DPSENDFLAGS enumeration indicating how the message should be sent. By default (flags = 0), the message is sent nonguaranteed.

DPSEND_ASYNC

Sends the message asynchronously. The method returns immediately. If this flag is not specified, the method does not return until the message has been sent (and acknowledged, if sent guaranteed). A DPSYS_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 DPSYS_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 be used only 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 DPSYS_SECUREMESSAGE system message.

msg

DirectPlayMessage object representing the data being sent. This object is obtained by using the DirectPlay4.CreateMessage method, and its own methods can be used to pack it with data.

priority

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.

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

timeOut

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. Zero indicates that no time-out should be used.

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

context

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

Return Values

Returns a DirectPlay-generated ID for the message.

Error Codes

If the method fails, an error is raised and Err.Number may be set to one of the following values:

This method returns DPERR_INVALIDPARAMS if the encrypted or signed flag is specified for a message that is not also specified as guaranteed. It returns DPERR_INVALIDPRIORITY if the priority value is not between 0 and 65535. It returns DPERR_UNSUPPORTED 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

This method 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, the message will be put into a send queue and the SendEx method will return immediately. A system message 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 flag is set in the session description.

If messages are sent using different priorities, signing and encryption might 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 might 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 nonsystem 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 nonsystem 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

DirectPlay4.Send, DirectPlay4.CancelMessage, DirectPlay4.CancelPriority