IDirectPlay8Peer::SendTo Method

Transmits data to another peer or group within the session by sending a message to the appropriate message handlers. The message can be sent synchronously or asynchronously.

Syntax

HRESULT SendTo(      

    const DPNID dpnid,
    const DPN_BUFFER_DESC *const pBufferDesc,
    const DWORD cBufferDesc,
    const DWORD dwTimeOut,
    void *const pvAsyncContext,
    DPNHANDLE *const phAsyncHandle,
    const DWORD dwFlags
);

Parameters

dpnid

[in] Identifier of the peer or group that receives data. Set this parameter to DPNID_ALL_PLAYERS_GROUP to send a message to all players in the session.

pBufferDesc

[in] Pointer to a DPN_BUFFER_DESC structure that contains the data to be sent.

cBufferDesc

[in] Number of DPN_BUFFER_DESC structures pointed to by pBufferDesc. There can be up to eight buffers in this version of Microsoft?DirectPlay?

dwTimeOut

[in] Number of milliseconds to wait for the message to send. If the message has not been sent by the dwTimeOut value, it is deleted from the send queue. If you set this parameter to 0, the message remains in the send queue until it is sent or until the link is dropped.

pvAsyncContext

[in] Pointer to the user-supplied context, which is returned in the pvUserContext member of the DPN_MSGID_SEND_COMPLETE system message. This parameter is optional and can be set to NULL.

phAsyncHandle

[out] A DPNHANDLE. When the method returns, phAsyncHandle will point to a handle that you can pass to IDirectPlay8Peer::CancelAsyncOperation to cancel the operation. This parameter must be set to NULL if you set the DPNSEND_SYNC flag in dwFlags.

dwFlags

[in] Flags that describe send behavior. You can set one or more of the following flags.

DPNSEND_SYNC

Process the IDirectPlay8Peer::SendTo request synchronously.

DPNSEND_NOCOPY

Use the data in the DPN_BUFFER_DESC structure and do not make an internal copy. This can be a more efficient method of sending data. However, it is less robust because modifying or deleting the data before receiving the DPN_MSGID_SEND_COMPLETE message can cause erroneous data to be sent. This flag cannot be combined with DPNSEND_NOCOMPLETE.

DPNSEND_NOCOMPLETE

Does not send the DPN_MSGID_SEND_COMPLETE to the message handler. This flag cannot be used with DPNSEND_NOCOPY or DPNSEND_GUARANTEED. Additionally, when using this flag the pvAsyncContext must be NULL.

DPNSEND_COMPLETEONPROCESS

Sends the DPN_MSGID_SEND_COMPLETE to the message handler when this message has been delivered to the target and the target's message handler returns from indicating its reception. There is additional internal message overhead when this flag is set, and the message transmission process might become significantly slower. If you set this flag, DPNSEND_GUARANTEED must also be set.

DPNSEND_GUARANTEED

Sends the message by a guaranteed method of delivery.

DPNSEND_PRIORITY_HIGH

Sets the priority of the message to high. This flag cannot be used with DPNSEND_PRIORITY_LOW.

DPNSEND_PRIORITY_LOW

Sets the priority of the message to low. This flag cannot be used with DPNSEND_PRIORITY_HIGH.

DPNSEND_NONSEQUENTIAL

If this flag is set, the target application will receive the messages in the order that they arrive at the user's computer. If this flag is not set, messages are delivered sequentially, and will be received by the target application in the order that they were sent. Doing so might require buffering incoming messages until missing messages arrive.

DPNSEND_NOLOOPBACK

Suppresses the DPN_MSGID_RECEIVE system message to your message handler when you are sending to a group that includes the local player. For example, this flag is useful if you are broadcasting to the entire session.

DPNSEND_COALESCE

Allows DirectPlay to combine packets when sending.

Return Value

Returns S_OK if this method is processed synchronously and is successful. By default, this method is run asynchronously and normally returns DPNSUCCESS_PENDING. It can also return one of the following error values.

DPNERR_CONNECTIONLOST	The service provider connection was reset while data was being sent.
DPNERR_GENERIC	An undefined error condition occurred.
DPNERR_INVALIDFLAGS	The flags passed to this method are invalid.
DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.
DPNERR_INVALIDPLAYER	The player ID is not recognized as a valid player ID for this game session.
DPNERR_TIMEDOUT	The operation could not complete because it has timed out.

Remarks

This method generates a DPN_MSGID_RECEIVE system message in the receiver's message handler. The data buffer is contained in the pReceiveData member of the associated structure.

Messages can have one of three priorities: low, normal, and high. To specify a low or high priority for the message, set the appropriate flag in dwFlags. If neither of the priority flags is set, the message will have normal priority. See Basic Networking for a discussion of send priorities.

When the IDirectPlay8Peer::SendTo request is completed, a DPN_MSGID_SEND_COMPLETE system message is normally posted to the sender's message handler. The success or failure of the request is contained in the hResultCode member of the associated structure. You can suppress send completions by setting the DPNSEND_NOCOMPLETE flag in dwFlags.

Send completions are typically posted on the source computer as soon as the message is sent. In other words, a send completion does not necessarily mean that the message has been processed on the target. It might still be in a queue. If you want to be certain that the message has been processed by the target, set the DPNSEND_COMPLETEONPROCESS flag in dwFlags. This flag ensures that the send completion will not be sent until the target's message handler has processed the message and returned.

If the DPNSEND_COALESCE flag is set in dwFlags, DirectPlay will try to coalesce up to 32 packets waiting in the queue into the outgoing frame. DirectPlay does not guarantee coalescence, even if the DPNSEND_COALESCE flag is set. Packets will only be coalesced if there is more than one message in the queue and the player receiving is running Microsoft DirectX?9.0 or later. All voice packets can be coalesced. Both guaranteed and non-guaranteed packets will be coalesced into the same frame. If the frame is dropped before it reaches its destination, only the guaranteed parts of the frame will be resent and no other data will be coalesced into the frame.

Note  Do not assume that resources such as the data buffer will remain valid until the method has returned. If you call this method asynchronously, the DPN_MSGID_SEND_COMPLETE message can be received and processed by your message handler before the call has returned. If your message handler deallocates or otherwise invalidates a resource such as the data buffer, that resource can become invalid at any time after the method has been called.

This method returns a DPNERR_GENERIC error value if the send computer is host with no other player connected and DPNSEND_SYNC and DPNSEND_NOLOOPBACK flags are set.