IDirectPlay8Client::Send
Transmits data to the server. The message can be sent synchronously or asynchronously.
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
- Pointer to a DPN_BUFFER_DESC structure that describes the data to send.
- cBufferDesc
- Number of DPN_BUFFER_DESC structures pointed to by pBufferDesc. There can only be one buffer in this version of Microsoft® DirectPlay®.
- dwTimeOut
- Number of milliseconds to wait for the message to be sent. If the message has not been sent by the dwTimeOut value, the message is not sent. If you do not want a time out for message sends, set this parameter to 0.
- pvAsyncContext
- Pointer to the user-supplied context, which is returned in the pvUserContext member of the DPN_MSGID_SEND_COMPLETE system message.
- phAsyncHandle
- 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
- Flags that describe send behavior. You can set one or more of the following flags.
- DPNSEND_SYNC
- Process the Send 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 to the server. 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 combined with DPNSEND_NOCOMPLETE.
- DPNSEND_NOCOMPLETE
- Does not send DPN_MSGID_SEND_COMPLETE 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 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 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 may necessitate buffering out of sequence messages until the missing messages arrive. Messages are simply delivered to the target application in the order that they are received.
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 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 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.
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 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.
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.
Windows NT/2000: Available as a redistributable for Windows 2000 and later.
Windows 95/98: Available as a redistributable for Windows 95 and later.
Header: Declared in Dplay8.h.