IDirectPlay4::Send

IDirectPlay4 Interface

Sends a message to another player, to a group of players, or to all players in the session. To send a message to another player, specify the target player's player ID. To send a message to a group of players, send the message to the group ID assigned to the group. To send a message to the entire session, send the message to the player ID DPID_ALLPLAYERS. Messages can be sent using either a guaranteed or nonguaranteed protocol on a per message basis. If the session is being hosted on a secure server, messages can be sent encrypted (to ensure privacy) or digitally signed (to ensure authenticity) on a per message basis.

Syntax

HRESULT Send(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPVOID lpData,
  DWORD dwDataSize
  );

Parameters

idFrom
ID of the sending player. The player ID must correspond to one of the local players on this computer.
idTo
The destination ID of the message. To send a message to another player, specify the ID of the player. To send a message to all the players in a group, specify the ID of the group. To send a message to all the players in the session, use the constant symbol DPID_ALLPLAYERS. To send a message to the server player, specify the constant symbol DPID_SERVERPLAYER. A player cannot send a message to itself.
dwFlags
Indicates how the message should be sent. By default (dwFlags = 0), the message is sent nonguaranteed.
DPSEND_ENCRYPTED
Sends the messages encrypted. This can only be done in a secure session. This flag can only be used if the DPSEND_GUARANTEED flag is also set. The message will be sent as a DPMSG_SECUREMESSAGE system message.
DPSEND_GUARANTEED
Sends the message by using a guaranteed method of delivery.
DPSEND_SIGNED
Sends the message with a digital signature. This can only be done in a secure session. This flag can only be used if the DPSEND_GUARANTEED flag is also set. The message will be sent as a DPMSG_SECUREMESSAGE system message.
lpData
Pointer to the data being sent.
dwDataSize
Length of the data being sent.

Return Value

Returns DP_OK if successful or one of the following error values:
DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG

This method returns DPERR_INVALIDPARAMS if the encrypted or signed flag is specified for a message that is not also specified as guaranteed. It returns DPERR_NOTLOGGEDIN when the client application tries to send a secure message without first logging in.

If a message is sent to a group, a return value of DP_OK does not necessarily mean that every player in the group got the message. If the message was sent guaranteed, DP_OK means that DirectPlay made a best effort to send it to all the players in the group. Typically, players that don't receive the message are killed because there is a problem with their connection.

Remarks

Use IDirectPlay4::SendEx for asynchronous send options.

Messages can be sent guaranteed or nonguaranteed. By default, messages are sent nonguaranteed, which means that DirectPlay does no verification that the message reached the intended recipient. Sending a guaranteed message takes much longer — a minimum of two to three times longer than nonguaranteed messages. Applications should try to minimize sending guaranteed messages as much as possible and to design the application to tolerate lost messages. All the service providers shipped with DirectPlay perform integrity checks on the data to protect against corruption. Any message sent using this method is guaranteed to be free from corruption.

System messages are always sent guaranteed, whether or not the service provider natively supports guaranteed messages, and whether or not you set the DirectPlay protocol flag. The DirectPlay protocol will be used automatically to send system messages guaranteed.

For non-system messages, if an application sets the DirectPlay protocol flag and sends a message guaranteed (by setting the DPSEND_GUARANTEED flag), the message will be sent guaranteed whether the service provider supports guaranteed messages or not.

For non-system messages, if an application does not set the DirectPlay protocol flag and sends a message guaranteed, the message will be sent guaranteed only if the service provider supports it. If the service provider does not support guaranteed messages, the message will not be sent guaranteed, regardless of the DPSEND_GUARANTEED flag.

An application invokes the DirectPlay protocol by setting the DPSESSION_DIRECTPLAYPROTOCOL flag when creating a session.

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. The exception to this rule is if the DPSESSION_NOMESSAGEID was specified in the session description (DPSESSIONDESC2). Then 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 based on the message ID.

When DPSESSION_NOMESSAGEID is used, the idFrom parameter has no meaning and the idTo parameter is used simply to direct the message to the correct target computer. If the target computer has more than one player on it, it cannot be determined whose receive queue the message will appear in. When the message is received, it will appear to have come from player DPID_UNKNOWN.

There is no limit to the size of messages that can be transmitted using the Send method. DirectPlay will automatically break up large messages into packets (packetize) and reassemble them on the receiving end. Beware of sending large messages nonguaranteed — if even one of the packets fails to reach the receiver, the entire message is ignored. The application can determine the maximum size of a message before it starts packetizing by calling GetCaps and examining the dwMaxBufferSize member of the DPCAPS structure.

When you send an encryted or signed message, it is not delivered as an application message, but as a system message, DPMSG_SECUREMESSAGE.

See Also

IDirectPlay4::Receive, IDirectPlay4::SendEx, IDirectPlay4::SendChatMessage, DPMSG_SECUREMESSAGE

Top of Page Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.