DirectPlay4.Send

The DirectPlay4.Send method sends a message to another player, to a group of players, or to all players in the session.

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.

object.Send(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPSENDFLAGS, _
    msg As DirectPlayMessage) 

Parameters

object

Object expression that resolves to a DirectPlay4 object.

fromPlayerId

ID of the sending player. The player ID must correspond to one of the local players on the computer.

toPlayerId

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 DPID_ALLPLAYERS. To send a message to the server player, specify the constant DPID_SERVERPLAYER. A player cannot send a message to itself.

flags

Value indicating how the message should be sent. By default (flags = 0), the message is sent nonguaranteed.

DPSEND_ENCRYPTED

Sends the message 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 DPSYS_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_SIGNED flag is also set. The message will be sent as a DPSYS_SECUREMESSAGE system message.

msg

DirectPlayMessage object representing the data being sent. This object is obtained by using the DirectPlay4.CreateMessage method, and its own methods can be used to pack it with data.

Error Codes

If the method fails, an error is raised and Err.Number may be set to one of the following values:

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 on.

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 removed from the session because there is a problem with their connection.

Remarks

Use DirectPlay4.SendEx for asynchronous send options.

Nonsystem messages can be sent guaranteed or nonguaranteed. By default, nonsystem messages are sent nonguaranteed, which means that DirectPlay does not verify 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.

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 nonsystem 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 nonsystem 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.

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.

Players cannot send messages to themselves. If a player sends a message to a group that it is part of or to DPID_ALLPLAYERS, the player will not receive a copy of that message. The exception to this rule is if the DPSESSION_NOMESSAGEID was specified in the session description. Then a player can 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.

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 by 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 packet by calling GetCaps and examining the lMaxBufferSize member of the DPCAPS type.

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

See Also

DirectPlay4.Receive, DirectPlay4.SendChatMessage, CONST_DPIDFLAGS