| ?/TD> |
| Microsoft DirectX 9.0 |
Transmits data to the server. The message can be sent synchronously or asynchronously.
Syntax
HRESULT Send(
const DPN_BUFFER_DESC *const pBufferDesc, const DWORD cBufferDesc, const DWORD dwTimeOut, void *const pvAsyncContext, DPNHANDLE *const phAsyncHandle, const DWORD dwFlags );
Parameters
- 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 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.
- phAsyncHandle
- [in, out] A DPNHANDLE. When the method returns, phAsyncHandle will point to a handle that you can pass to IDirectPlay8Client::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 IDirectPlay8Client::Send 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 to the server. 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 DPN_MSGID_SEND_COMPLETE to the message handler. This flag cannot be used with DPNSEND_NOCOPY or DPNSEND_GUARANTEED. Additionally, when using this flag pvAsyncContext must be NULL.
- DPNSEND_COMPLETEONPROCESS
- Send 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
- 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 if you are sending to yourself.
- DPNSEND_NONSEQUENTIAL
- If the flag is not set, messages are delivered to the target application in the order that they are sent, which can necessitate buffering out of sequence messages until the missing messages arrive. Messages are delivered to the target application in the order that they are received.
- 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 generally returns DPNSUCCESS_PENDING or one of the following error values.
DPNERR_INVALIDFLAGS The flags passed to this method are invalid. DPNERR_TIMEDOUT The operation could not complete because it has timed out.
Remarks
This method generates a DPN_MSGID_RECEIVE system message in the server'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 IDirectPlay8Client::Send 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 associate structure. You can suppress the send completion by setting the DPN_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 might still be in a queue. If you want to be certain that the message has been processed by the target, set the DPN_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.