HRESULT Send(DPID idFrom, DPID idTo, DWORD dwFlags,
LPVOID lpData, DWORD dwDataSize);
Sends messages to other players, to a group of players, or to all players in the session.
·Returns DP_OK if successful, the number of messages waiting for transmission in DirectPlay's internal queue, or one of the following error values:
idFrom
ID of the sending player. The player ID must correspond to one of the local players on this computer.
idTo
ID of the player to send the message to, the group ID of the group of players to send the message to, or DPID_ALLPLAYERS to send the message to all players in the session. If the DPSEND_OPENSTREAM or DPSEND_CLOSESTREAM flags are used, then this parameter must be a player ID.
dwFlags
Indicates how the message should be sent. If this parameter is set to 0, the message is sent nonguaranteed and at normal priority. DPSEND_OPENSTREAM and DPSEND_CLOSESTREAM are used to let DirectPlay and the service provider know that there will be a large number of guaranteed messages being sent to the player specified in idTo. If some efficiency can be gained by not opening and closing a guaranteed communication pipe (stream) for each message to that player, then the service provider may leave the stream open until the IDirectPlay2::Send method with a DPSEND_CLOSESTREAM flag for that player ID is called. DPSEND_OPENSTREAM and DPSEND_CLOSESTREAM are valid only for messages where idTo is a valid player ID. It is not required that a service provider support DPSEND_OPENSTREAM and DPSEND_CLOSESTREAM.
Sends the message by using a guaranteed method of delivery if it is available.
Sends the message high-priority. This will force the message to the front of the send queue for immediate transmission. The message will also go to the top of the receiving application's receive buffer.
Indicates an optimization hint to the service provider that there will be a lot of guaranteed messages being sent to this player.
Indicates that there will no longer be a lot of guaranteed messages being sent to this player.
lpData
Address of the data being sent. Set this parameter to NULL if there is no actual message to send. An application can do this if the DPSEND_OPENSTREAM or DPSEND_CLOSESTREAM flag is specified.
dwDataSize
Length of the data being sent.
To send a message to another player, specify the target player's ID. To send a message to a group of players, send the message to the ID assigned to the group. To send messages to the entire session, specify the DPID_ALLPLAYERS player ID. You cannot use the IDirectPlay2::Send method inside an IDirectDrawSurface2::Lock / IDirectDrawSurface2::Unlock or IDirectDrawSurface2::GetDC / IDirectDrawSurface2::ReleaseDC method pair.
A player cannot send a message to itself. If a player sends a message to a group that it is part of or to DPID_ALLPLAYERS, it will not receive a copy of that message.
If DPSESSION_NOMESSAGEID was specified in the session description, it is possible for a player to receive a message that it sent to a group. Because there is no DirectPlay message ID header on the message (indicating who sent the message), it cannot filter out messages from itself when the service provider implements group sends, and the application will need to be able to evaluate this based on the content of the message.
When DPSESSION_NOMESSAGEID is used, the message is sent to one of the local players on the target computer.
Messages can be sent guaranteed or nonguaranteed. By default, messages are sent nonguaranteed, which means that DirectPlay does not verify that the message reached the intended recipient. Sending a guaranteed message takes a minimum of two to three times longer than a nonguaranteed message. You should try to minimize the number of times your application sends guaranteed messages, and your application should be able to tolerate lost messages.
All the service providers shipped with DirectPlay perform integrity checks on the data to protect against corruption. Any message received will be verified, and if data corruption is detected, it will either be thrown away (if it was sent nonguaranteed) or it will be retransmitted (if it was sent guaranteed).
Note In this version of DirectPlay, DPSEND_GUARANTEED will guarantee delivery only if the service provider supports it. An application can find out if delivery will be guaranteed by calling the IDirectPlay2::GetCaps method and checking for the DPCAPS_GUARANTEEDSUPPORTED flag. If this flag is not set, then the DPSEND_GUARANTEED flag will be ignored and the message will be sent nonguaranteed. The next version of DirectPlay will implement guaranteed delivery on nonguaranteed service providers so the guaranteed supported CAPS flag will always be present. If the application implements its own method of guaranteeing message delivery, it must be sure not to use the DPSEND_GUARANTEED flag. When testing the performance of your application, it is important to know if the service provider supports guaranteed messaging or not. If it does not, then every place you specified DPSEND_GUARANTEED will run slower with the next version of DirectPlay.