IDirectPlay8Server::SendTo

Transmits data to a client or group within the session. 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 client or group to receive 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 describes the data to send.

cBufferDesc

[in] 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.

phAsyncHandle

[out] A DPNHANDLE. When the method returns, phAsyncHandle will point to a handle that you can pass to IDirectPlay8Server::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 may be a more efficient method of sending data. However, it is less robust because the sender might be able to modify the message before the receiver has processed it. This flag cannot be used with DPNSEND_NOCOMPLETE.

DPNSEND_NOCOMPLETE

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

DPNSEND_COMPLETEONPROCESS

Send 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

Send 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_NOLOOPBACK

Suppress 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_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.

Return Values

Returns S_OK if this method is processed synchronously and is successful. By default, this method is run asynchronously and generally returns DPNSUCCESS_PENDING or one of the following error values.

Remarks

This method generates a DPN_MSGID_RECEIVE system message in the receiver's message handler. The data 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 SendTo request is completed, a DPN_MSGID_SEND_COMPLETE system message is 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 the send completion 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 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.

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.