IDirectPlay8Peer::SendTo

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.

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. To send a message to all players in the session, set this parameter to DPNID_ALL_PLAYERS_GROUP.

pBufferDesc

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

cBufferDesc

[in] The number of DPN_BUFFER_DESC structures pointed to by pBufferDesc. There can be only one buffer 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 may 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 SendTo request synchronously.

DPNSEND_NOCOPY

Use the data in the DPN_BUFFER_DESC structure and do not make an internal copy. This might be a more efficient method of sending data, however, it is less robust because the sender might be able to modify message before the receiver has processed it. 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. 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 may 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 may 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. This flag is useful if, for example, you are broadcasting to the entire session.

Return Values

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.

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, or 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. For a discussion of send priorities, see Basic Networking.

When the 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.

If a player joins a game and needs to send multiple messages immediately, the player should first send a message with the DPNSEND_COMPLETEONPROCESS flag set. When the DPN_MSGID_SEND_COMPLETE message is returned, the application can begin sending messages. If the player does not do this, some of the messages might need to be queued on the receiver and, if too much data arrives, the queue can grow faster than the receiver can handle the messages. This might result in lost data. After a player is established in the game, however, throttling in DirectPlay will control the data flow by using message timeouts or the GetSendQueueInfo method. For more information, see Optimizing Network Usage.

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 may 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.

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 may 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 may become invalid at any time after the method has been called.

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

Requirements

  Windows NT/2000/XP: Available as a redistributable for Windows 2000 and later.
  Windows 98/Me: Available as a redistributable for Windows 98 and later.
  Header: Declared in Dplay8.h.