Microsoft SDK for Java

send

This method of the DirectPlay2 Class sends messages to other players, to a group of players, or to all players in the session.

Syntax

public void send(int fromPlayerId, int toPlayerId, int flags, byte[] data, int dataSize);

Parameters

fromPlayerId The player ID of the sending player. The player ID must correspond to one of the local players on this computer.
toPlayerId The player 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 to all players in the session. If DPSEND_OPENSTREAM or DPSEND_CLOSESTREAM flags are used, this parameter must be a player ID.
flags One value of DPSEND_ type, indicating how the message should be sent. If this parameter is set to 0, the message is sent nonguaranteed and at normal priority.
data Array variable that contains the data being sent. Set to null if there is no actual message to send.
dataSize Length of the data being sent.

Remarks

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 messages to the entire session, specify the player ID DPID_ALLPLAYERS. The send method cannot be used inside a lock / unlock or a getDC / 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. Since 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 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 a nonguaranteed message. Applications should try to minimize sending guaranteed messages as much as possible and 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 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 DirectPlay2, DPSEND_GUARANTEED will only guarantee delivery if the service provider supports it. An application can find out if delivery will be guaranteed by calling getCaps and checking for the DPCAPS_GUARANTEEDSUPPORTED flag. If this flag is not set, 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. If it does not, every place you specified DPSEND_GUARANTEED will run slower with the next version of DirectPlay.

See Also

receive

© 1999 Microsoft Corporation. All rights reserved. Terms of use.