Class DirectPlay2

public class DirectPlay2 implements IDirectPlay2
{
  // Methods
  public void addPlayerToGroup(int groupId, int playerId);
  public void close();
  public IDirectPlay2 create(_Guid g);
  public int createGroup(String friendlyName, String formalName,
        byte[] data, int dataSize);
  public int createPlayer(String friendlyName, String formalName,
        int receiveEvent, byte[] data, int dataSize);
  public void deletePlayerFromGroup(int groupId, int playerId);
  public void destroyGroup(int groupId);
  public void destroyPlayer(int playerId);
  public void enumGroupPlayers(int groupId, _Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context,
        int flags);
  public void enumGroups(_Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context,
        int flags);
  public void enumPlayers(_Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context,
        int flags);
  public void enumServiceProviders(
        IEnumServiceProvidersCallback callback, IUnknown context);
  public void enumSessions(DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password, int timeOut,
        IEnumSessionsCallback2 callback, IUnknown context,
        int flags);
  public void getCaps(DPCaps caps, int flags);
  public void getGroupData(int groupId, byte[] data,
        int[] dataSize, int flags);
  public String getGroupFormalName(int groupId);
  public String getGroupFriendlyName(int groupId);
  public int getMessageCount(int playerId);
  public void getPlayerAddress(int playerId, byte[] addressData,
        int[] addressSize);
  public int getPlayerAddressSize(int playerId);
  public void getPlayerCaps(int playerId, DPCaps caps, int flags);
  public void getPlayerData(int playerId, byte[] data,
        int[] dataSize, int flags);
  public String getPlayerFormalName(int playerId);
  public String getPlayerFriendlyName(int playerId);
  public void getSessionDesc(DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String[] sessionName, String[] password);
  public void initialize(_Guid guid);
  public void open(DPSessionDesc sessionDesc, _Guid sessionGuid,
        _Guid applicationGuid, String sessionName,
        String password, int flags);
  public void receive(int[] fromPlayerId, int[] toPlayerId,
        int flags, byte[] data, int[] dataSize);
  public int receiveSize(int flags);
  public void send(int fromPlayerId, int toPlayerId, int flags,
        byte[] data, int dataSize);
  public void setGroupData(int groupId, byte[] data, int dataSize,
        int flags);
  public void setGroupName(int groupId, String friendlyName, String
        formalName, int flags);
  public void setPlayerData(int playerId, byte[] data,
        int dataSize, int flags);
  public void setPlayerName(int playerId, String friendlyName,
        String formalName, int flags);
  public void setSessionDesc(DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password, int flags);
  public void stopEnumGroupPlayers();
  public void stopEnumGroups();
  public void stopEnumPlayers();
  public void stopEnumServiceProviders();
  public void stopEnumSessions();
}

Applications use the methods of the DirectPlay2 class to create Microsoft® DirectPlay®2 objects and work with system-level variables.

Caution The enumeration methods provided in this class are fundamentally different from their native code counterparts. While the native code implementation return type is a boolean, the Java return type is void. This makes stopping an enumeration more difficult (you can not return false to stop the enumeration). You can use the following DirectPlay methods to stop enumerations:

• stopEnumSessions
• stopEnumGroups
• stopEnumGroupPlayers
• stopEnumPlayers
• stopEnumServiceProviders

The stopEnumSessions is the most important method of these, because a session enumeration can proceed infinitely.

Methods

addPlayerToGroup

public void addPlayerToGroup(int groupId, int playerId);

Adds an existing player to an existing group.

Return Value:

No return value.

Parameter	Description
groupId	The ID of the group to be augmented.
playerId	The ID of the player to be added to the group.

Remarks:

Groups cannot be added to other groups, but players can be members of multiple groups. A DPSYS_ADDDIRECTPLAYERTOGROUP system message will be generated and sent to all the other players.

See Also: createGroup, deletePlayerFromGroup, DPSYS_ADDDIRECTPLAYERTOGROUP

close

public void close();

Closes a previously opened session.

Return Value:

No return value.

Remarks:

All locally created players will be destroyed, and corresponding DPSYS_DESTROYPLAYERORGROUP system messages are sent to other session participants. However, groups will not be destroyed; use destroyGroup to destroy the group.

See Also: destroyPlayer, DPMSG_DESTROYPLAYERORGROUP, open

create

public IDirectPlay2 create(_Guid g);

Creates a DirectPlay object.

Return Value:

Returns the DirectPlay object if successful; null otherwise.

Parameter	Description
g	A _Guid object that specifies the globally unique identifier (GUID) that represents the service provider that should be created.

Remarks:

This function attempts to initialize a DirectPlay object. You should call the enumServiceProviders method immediately before initialization to determine what types of service providers are available (enumServiceProviders fills in the g parameter for create).

See Also: enumServiceProviders

createGroup

public int createGroup(String friendlyName, String formalName, byte[] data,
        int dataSize);

Creates a logical group of players in the current session.

Return Value:

Returns a unique DirectPlay ID that identifies the new group.

Parameter	Description
formalName	The formal name of the group. Use null to indicate that the group has no formal name.
friendlyName	The friendly name of the group. Use null to indicate that the group has no friendly name.
data	A block of application-defined remote data to associate with the group ID. Null indicates that the group has no initial data. The data specified here is assumed to be remote data that will be propagated to all the other applications in the session as if setGroupData were called.
dataSize	The size, in bytes, of data.

Remarks:

Messages can be sent to a group, and DirectPlay will forward the message to every player in the group. The Group ID returned to the caller should be used to identify the group for message passing and data association. Player and Group identifiers assigned by DirectPlay will always be unique within the session. This method will generate a DPSYS_CREATEPLAYERORGROUP message that will be sent to all the other players.

See Also: DPMSG_CREATEPLAYERORGROUP, destroyGroup, enumGroups, enumGroupPlayers, send

createPlayer

public int createPlayer(String friendlyName, String formalName,
        int receiveEvent, byte[] data, int dataSize);

Creates a local player for the current session.

Return Value:

Returns a unique DirectPlay ID that identifies the new player.

Parameter	Description
formalName	The formal name of the player. Use null to indicate that the player has no formal name information.
friendlyName	The friendly name of the player. Use null to indicate that the player has no friendly name.
receiveEvent	An event object created by the application that will be triggered by DirectPlay2 when a message addressed to this player is received.
data	A block of application-defined remote data to associate with the group ID. Null indicates that the group has no initial data. The data specified here is assumed to be remote data that will be propagated to all the other applications in the session as if setPlayerData were called.
dataSize	The size, in bytes, of data.

Remarks:

A single process can have multiple local players that communicate through a DirectPlay object with any number of other local or remote players running on multiple computers. The player ID returned to the caller should be used to identify the player for message passing and data association. Player and Group IDs assigned by DirectPlay will always be unique within the session.

The application can associate an initial name with the player at its creation (see setPlayerName). The names in friendlyName and formalName are provided for human use only; they are not used internally and need not be unique.

Upon successful completion, this method sends a DPSYS_CREATEPLAYERORGROUP system message to all of the other players in the session announcing that a new player has joined the session.

See Also: DPMSG_CREATEPLAYERORGROUP, destroyPlayer, enumPlayers, receive, send, setPlayerName

deletePlayerFromGroup

public void deletePlayerFromGroup(int groupId, int playerId);

Removes a player from a group.

Return Value:

No return value.

Parameter	Description
groupId	The group ID of the group to be adjusted.
playerId	The ID of the player to be removed from the group.

Remarks:

A DPSYS_DELETEPLAYERFROMGROUP system message is generated to inform the other players of this change.

See Also: addPlayerToGroup, DPMSG_DELETEPLAYERFROMGROUP

destroyGroup

public void destroyGroup(int groupId);

Deletes a group from the session. The ID belonging to this group will not be reused during the current session.

Return Value:

No return value.

Parameter	Description
groupId	The ID of the group being removed from the game.

Remarks:

It is not necessary to empty a group before deleting it. The individual players belonging to the group are not destroyed. This method will generate a DPSYS_DELETEPLAYERFROMGROUP for each player in the group, and then generate a DPSYS_DESTROYPLAYERORGROUP system message.

See Also: createGroup, DPMSG_DESTROYPLAYERORGROUP

destroyPlayer

public void destroyPlayer(int playerId);

Deletes a player from the session, removes any pending messages destined for that player from the message queue, and removes the player from any groups to which that player belonged. The player ID will not be reused during the current session.

Return Value:

No return value.

Parameter	Description
playerId	The ID of the player that is being removed from the session.

Remarks:

This method will generate a DPSYS_DELETEPLAYERFROMGROUP message for each group that the player belongs to, and then generate a DPSYS_DESTROYPLAYERORGROUP system message.

See Also: createPlayer, DPMSG_DESTROYPLAYERORGROUP

enumGroupPlayers

public void enumGroupPlayers(int groupId, _Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context, int flags);

Enumerates all of the players of a particular group existing in the current session. Use the stopEnumGroupPlayers method to stop the enumeration.

Return Value:

No return value.

Parameter	Description
groupId	The Group ID, whose players are to be enumerated.
sessionGuid	The GUID of the DirectPlay session of interest. This parameter must be set to null unless the DPENUMPLAYERS_SESSION flag is specified.
callback	The callback interface that contains the callback function to be called for every player in the group.
context	A caller-defined context that is passed to each enumeration callback.
flags	The flags to pass to the callback function.

Remarks:

By default, this method will enumerate group players by using the local player list for the current session. This method cannot be called from within an enumSessions enumeration.

See Also: createPlayer, destroyPlayer, addPlayerToGroup, deletePlayerFromGroup, stopEnumGroupPlayers

enumGroups

public void enumGroups(_Guid sessionGuid, IEnumPlayersCallback2 callback,
        IUnknown context, int flags);

Enumerates the groups available to a session. Use the stopEnumGroups method to stop the enumeration.

Return Value:

No return value.

Parameter	Description
sessionGuid	The GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified.
callback	The callback interface that contains the callback function to be called for every group in the session.
context	A caller-defined context that is passed to each enumeration callback.
flags	The value can be 0 or DPENUMPLAYERS_SESSION. This flag is passed to the callback function.

Remarks:

By default, this method will enumerate using the local player list for the current session. The DPENUMPLAYERS_SESSION flag can be used, along with a session instance GUID, to request that a session's host provide its list for enumeration. This method cannot be called from within an enumSessions enumeration. Furthermore, use of the DPENUMPLAYERS_SESSION flag with this method must occur after the enumSessions method has been called and before any calls to close or open.

See Also: createGroup, destroyGroup, enumSessions, stopEnumGroups

enumPlayers

public void enumPlayers(_Guid sessionGuid, IEnumPlayersCallback2 callback,
        IUnknown context, int flags);

Enumerates the players in a session. Use the stopEnumPlayers method to stop the enumeration.

Return Value:

No return value.

Parameter	Description
sessionGuid	A GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified.
callback	The callback instance that contains the callback function that will be called for every group in the session.
context	A caller-defined context that is passed to each enumeration callback.
flags	One or more values of the DPENUMPLAYERS_ type. The values are also passed to the callback function.

Remarks:

By default, this method will enumerate players in the current open session. Groups can also be included in the enumeration by using the DPENUMPLAYERS_GROUP flag. The DPENUMPLAYERS_SESSION flag can be used with a session instance GUID to request that a session host provide its list for enumeration. This method cannot be called from within an enumSessions enumeration. Also, use of the DPENUMPLAYERS_SESSION flag with this method must occur after the enumSessions method has been called, and before any calls to close or open.

See Also: createPlayer, destroyPlayer, enumSessions, stopEnumPlayers

enumServiceProviders

public void enumServiceProviders(IEnumServiceProvidersCallback callback,
        IUnknown context);

Enumerates the DirectPlay service providers installed on the system. Use the stopEnumServiceProviders method to stop the enumeration.

Return Value:

No return value.

Parameter	Description
callback	The IEnumServiceProvidersCallback interface that contains the callback function to be called with a description of each DirectPlay service provider interface installed in the system.
context	The caller-defined data that is passed to the callback function each time the function is invoked.

Remarks:

This method enumerates service providers installed in the system, even though the system may not be capable of using those service providers. For example, a TAPI service provider may be enumerated, even though the system may not have a modem installed.

See Also: stopEnumServiceProviders

enumSessions

public void enumSessions(DPSessionDesc sessionDesc, _Guid sessionGuid,
        _Guid applicationGuid, String sessionName, String password,
        int timeOut, IEnumSessionsCallback2 callback, IUnknown context, int
        flags);

Enumerates the sessions available to this DirectPlay object. Use the stopEnumSessions method to stop the enumeration.

Return Value:

No return value.

Parameter	Description
sessionDesc	A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this structure will be enumerated. If a password is required, the password field should be set accordingly.
sessionGuid	The GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified.
applicationGuid	The GUID of the application.
sessionName	The Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use.
password	The Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
timeOut	The total amount of time (in milliseconds) that DirectPlay will wait for replies to the enumeration message (not the time between each enumeration). It is recommended that this parameter be set to zero, so DirectPlay can compute the default timeout appropriate for the service provider.
callback	The callback interface that contains the callback function to be called for each DirectPlay session responding.
context	A user-defined context that is passed to each enumeration callback.
flags	A value of the DPENUMSESSIONS_ type. Set to 0 or DPENUMSESSIONS_AVAILABLE, to enumerate only available sessions.

Remarks:

This method is usually called immediately after the DirectPlay object is created using directPlayCreate. It cannot be called while connected to a session or after an application has created a session. enumSessions works by asking that the service provider locate one or more hosts on the network and send the hosts an enumeration request. The replies received make up the sessions that are enumerated. The amount of time DirectPlay spends listening for these replies is controlled by the f1 parameter. When this time interval has expired, your callback will be notified with the DPESC_TIMEDOUT flag. At this point, you may choose to continue the enumeration by setting f1 to a new value and returning 1 or by returning 0 to cancel the enumeration. It is recommended that f1 be set to 0. In that case, DirectPlay will compute a time out that is appropriate for the service provider.

Usually, only sessions that can be joined are enumerated. If the DPENUMSESSIONS_ALL flag is specified, sessions will be enumerated even if the creation of new players has been disabled. Be aware that the application will still not be able to join these sessions.

If the application was not launched by a lobby, the service provider may display a dialog to obtain information from the user to perform the enumeration. For example, the Microsoft serial service provider will ask for COM port settings, the modem service provider will ask for a phone number, and the Internet service provider will ask for an IP address of the host.

Password protected sessions will not be enumerated unless you supply a correct password.

See Also: open, stopEnumSessions

getCaps

public void getCaps(DPCaps caps, int flags);

Retrieves the capabilities of this DirectPlay object.

Return Value:

No return value.

Parameter	Description
caps	A DPCaps object that receives the capabilities of the DirectPlay object. The size field of the DPCaps object must be filled in before using getCaps.
flags	If this parameter is set to 0, the capabilities will be computed for nonguaranteed messaging. DPGETCAPS_GUARANTEED Retrieves the capabilities for a guaranteed message delivery.

Remarks:

The difference between this method and getPlayerCaps is that this method returns the capabilities of the current session and getPlayerCaps returns the capabilities of the requested player.

See Also: com.ms.directX.DPCaps, getPlayerCaps, send

getGroupData

public void getGroupData(int groupId, byte[] data, int[] dataSize,
        int flags);

Retrieves data for a group of players.

Return Value:

No return value.

Parameter	Description
groupId	The group ID that data is being requested for.
data	The buffer where the application-specific group data is to be written. Set this parameter to NULL to request only the size of data. The dataSize parameter will be set to the size required to hold the data.
dataSize	The size of the buffer before the method is called. After the method returns, this parameter will be set to the size (in bytes) of the group data. If the buffer was too small (DPERR_BUFFERTOOSMALL), this parameter will be set to the buffer size required (see the note about passing null as an argument for other behavior regarding DPERR_BUFFERTOOSMALL).
flags	If this parameter is set to 0, the remote data will be retrieved.

Remarks:

DirectPlay can maintain two types of group data: local and remote. The application must specify which type of data to retrieve. Local data was set by this DirectPlay2 object by using the DPSET_LOCAL flag. Remote data might have been set by any application in the session by using the DPSET_REMOTE flag.

You can pass a null for the data buffer parameter to retrieve the size for the buffer. However, when you do this you must put the code into a try...catch block, because a DPERR_BUFFERTOOSMALL error is generated. The following example shows how you might implement a try...catch block to catch the error.

int  hr=0;
try {
      Glb.glpDPlay2.getGroupData(dpID,null, dataSize,DPGET_REMOTE);
    }
catch (ComException e){ hr= e.getHResult();}

// Check for the DPERR_BUFFERTOOSMALL error
if (hr!=DPERR_BUFFERTOOSMALL){
       //problem...
    }

See Also: com.ms.directX.DirectXConstants.DPGET_REMOTE, com.ms.directX.DirectXConstants.DPGET_LOCAL

getGroupFormalName

public String getGroupFormalName(int groupId);

Retrieves the formal name associated with the group.

Return Value:

Returns the formal name associated with the group.

Parameter	Description
groupId	The ID of the group, whose name is being requested.

getGroupFriendlyName

public String getGroupFriendlyName(int groupId);

Retrieves the friendly name associated with the group.

Return Value:

Returns the friendly name associated with the group.

Parameter	Description
groupId	The ID of the group, whose name is being requested.

getMessageCount

public int getMessageCount(int playerId);

Queries for the number of messages in a specific local player's message receive queue.

Return Value:

Returns the message count.

Parameter	Description
playerId	The layer ID that the message count is requested for. The player must be local.

See Also: receive

getPlayerAddress

public void getPlayerAddress(int playerId, byte[] addressData,
        int[] addressSize);

Retrieves the DirectPlay address for a player. The DirectPlay address is a network address for a player using a specific service provider.

Return Value:

No return value.

Parameter	Description
playerId	Player ID that the address is being requested for.
addressData	Address of a buffer where the DirectPlay2 address is to be written. Set this parameter to NULL to request only the size of data. The addressSize parameter will be set to the size required to hold the data.
addressSize	The size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the group data. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the buffer size that is required.

getPlayerAddressSize

public int getPlayerAddressSize(int playerId);

Retrieves the DirectPlay address size for a player.

Return Value:

Returns the address size.

Parameter	Description
playerId	The player ID that the address size is being requested for.

getPlayerCaps

public void getPlayerCaps(int playerId, DPCaps caps, int flags);

Obtains the current capabilities of a specified player.

Return Value:

No return value.

Parameter	Description
playerId	The player ID that the capabilities should be computed for.
caps	A DPCaps object that receives the capabilities of the player. The size field of the DPCaps object must contain a value before using getPlayerCaps.
flags	If this parameter is set to 0, the capabilities will be computed for nonguaranteed messaging.

Remarks:

The difference between this method and getCaps is that this method returns the capabilities of the requested player; getCaps returns the capabilities of the current session.

See Also: com.ms.directX.DPCaps, getCaps, send, com.ms.directX.DirectXConstants.DPGETCAPS_GUARANTEED

getPlayerData

public void getPlayerData(int playerId, byte[] data, int[] dataSize,
        int flags);

Retrieves player data for the specified player ID.

Return Value:

No return value.

Parameter	Description
playerId	ID of the player for which data is being requested.
data	Application-specific player data. Set this parameter to null to request only the size of data. The dataSize parameter will be set to the size required to hold the data.
dataSize	The size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the group data. If the buffer was too small (DPERR_BUFFERTOOSMALL), this parameter will be set to the buffer size required.
flags	If this parameter is set to 0, the remote data will be retrieved. DPGET_REMOTE Retrieves the current data from the remote shared data space. DPGET_LOCAL Retrieves the local data set by this application.

getPlayerFormalName

public String getPlayerFormalName(int playerId);

Obtains the formal name associated with a player.

Return Value:

Returns the name.

Parameter	Description
playerId	Player ID number for which the name information is being requested.

See Also: setPlayerName

getPlayerFriendlyName

public String getPlayerFriendlyName(int playerId);

Obtains the friendly name associated with a player.

Return Value:

Returns the name.

Parameter	Description
playerId	Player ID number for which the name information is being requested.

See Also: setPlayerName

getSessionDesc

public void getSessionDesc(DPSessionDesc sessionDesc, _Guid sessionGuid,
        _Guid applicationGuid, String[] sessionName, String[] password);

Retrieves a description of the specified session.

Return Value:

No return value.

Parameter	Description
sessionDesc	A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this structure will be enumerated. If a password is required, the password field should be set accordingly.
sessionGuid	The GUID of the session instance.
applicationGuid	The GUID of the application running in the session instance. It uniquely identifies the application so that DirectPlay connects only to other computers running the same application. This member can be set to GUID_NULL to enumerate sessions for any application.
sessionName	The Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use.
password	The Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.

initialize

public void initialize(_Guid guid);

Initializes the DirectPlay2 object.

Return Value:

No return value.

Parameter	Description
guid	The GUID used as the interface identifier.

Remarks:

Since the DirectPlay2 object is initialized when it is created, calling this method will always result in no action.

open

public void open(DPSessionDesc sessionDesc, _Guid sessionGuid,
        _Guid applicationGuid, String sessionName, String password,
        int flags);

Establishes a gaming session instance.

Return Value:

No return value.

Parameter	Description
sessionDesc	The DPSessionDesc object describing the session to be created or joined.
sessionGuid	The GUID of the DirectPlay session of interest.
applicationGuid	The GUID of the application running in the session instance. It uniquely identifies the application so that DirectPlay connects only to other computers running the same application. This member can be set to GUID_NULL to enumerate sessions for any application.
sessionName	Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use.
password	Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
flags	Can be one of the following flags: DPOPEN_CREATE DPOPEN_JOIN

Remarks:

An application may either create a new session (which other remote applications join) or join an existing session. open must be called before any local players are created. Before an application can join an existing session, it will use enumSessions to obtain a list of what sessions can be joined and their session descriptions. Attempting to join a session where adding new players is disabled, joining is disabled, or the player limit has been reached will result in no action.

See Also: close, enumSessions

receive

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

Retrieves a message from the message queue.

Return Value:

No return value.

Parameter	Description
fromPlayerId	A array that receives the player ID of the sender of the message.
toPlayerId	An array that receives the player ID of the receiver of the message.
flags	One or more values of DPRECEIVE_ type. Both DPRECEIVE_TOPLAYER and DPRECEIVE_FROMPLAYER can be specified, in which case receive will return whichever message is encountered first.
data	Array variable that receives the message data.
dataSize	The length of the array assigned to the data parameter.

Remarks:

Any message received from player ID DPID_SYSMSG is a system message that is generated by the host. For such messages, the application should interpret data as a generic system message and check for the type of message before processing it.

Messages that were sent to player ID DPID_SYSMSG as a way to broadcast them to all players, or to a group ID to send them to all the players in the group, still appear to come from the sending player ID. An application will only receive messages directed to a local player. A player cannot receive a message where the sender and receiver IDs are the same.

If DPSESSION_NOMESSAGEID is specified in the session description, the LPID_FROM and LPID_TO variables are meaningless.

All the service providers shipped with DirectPlay perform integrity checks on the data to protect against corruption. Any message received will be verified. If data corruption is detected, the message will either be thrown away (if it was sent nonguaranteed) or it will be retransmitted (if it was sent guaranteed).

See Also: send

receiveSize

public int receiveSize(int flags);

Retrieves the size of the message data associated with the next or specified message on the message queue.

Return Value:

Returns the size of the message data.

Parameter	Description
flags	Can be DPRECEIVE_ALL.

send

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

Sends messages to other players, to a group of players, or to all players in the session.

Return Value:

No return value.

Parameter	Description
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

setGroupData

public void setGroupData(int groupId, byte[] data, int dataSize, int flags);

Sets data for the group specified by the group ID.

Return Value:

No return value.

Parameter	Description
groupId	The group ID for which data is being set.
data	The data to be set. Set to NULL to clear any existing group data.
dataSize	Size of the data buffer.
flags	If this parameter is set to 0, the remote group data will be set and propagated using nonguaranteed messaging. See also: DPSET_REMOTE DPSET_LOCAL DPSET_GUARANTEED

setGroupName

public void setGroupName(int groupId, String friendlyName,
        String formalName, int flags);

Sets the name of a group after it has been created. A DPSYS_SETPLAYERORGROUPNAME system message will be sent to all the other players notifying them of the change, unless DPSESSION_NODATAMESSAGES is set in the session description.

Return Value:

No return value.

Parameter	Description
groupId	The ID of the group for which the name is being set.
friendlyName	The friendly name of the group.
formalName	The formal name of the group.
flags	If this parameter is set to 0, the name will be propagated to all the remote systems by using nonguaranteed message passing. See also: DPSET_GUARANTEED

setPlayerData

public void setPlayerData(int playerId, byte[] data, int dataSize,
        int flags);

Associates an application-specific data block with a player ID.

Return Value:

No return value.

Parameter	Description
playerId	The ID of the player for which data is being set.
data	The data to be set. Set this parameter to null to clear any existing player data.
dataSize	The size of the data.
flags	If this parameter is set to 0, the remote player data will be set and propagated by using nonguaranteed messaging. This parameter may be one or a combination of the following flags: DPSET_REMOTE DPSET_LOCAL DPSET_GUARANTEED

setPlayerName

public void setPlayerName(int playerId, String friendlyName,
        String formalName, int flags);

Sets the name of the player after it has been changed. A DPSYS_SETPLAYERORGROUPNAME system message will be sent to all other players notifying them of the change, unless DPSESSION_NODATAMESSAGES is set in the session description.

Return Value:

No return value.

Parameter	Description
playerId	The player ID for which data is being sent.
formalName	The formal name for the player. Use null if the player has no formal name.
friendlyName	The friendly name for the player. Use null if the player has no friendly name.
flags	If this parameter is set to 0, the name will be propagated to all the remote systems using nonguaranteed message passing.

See Also: DPMSG_SETPLAYERORGROUPNAME, getPlayerFormalName, getPlayerFriendlyName, send, com.ms.directX.DirectXConstants.DPSET_GUARANTEED

setSessionDesc

public void setSessionDesc(DPSessionDesc sessionDesc, _Guid sessionGuid,
        _Guid applicationGuid, String sessionName, String password,
        int flags);

This method is currently not supported. Changes the properties of the current session. This method works only when called on the computer that is the host of the session.

Return Value:

Returns DPERR_UNSUPPORTED.

Parameter	Description
sessionDesc	The DPSessionDesc object describing the session to be created or joined.
sessionGuid	The GUID of the DirectPlay session of interest.
applicationGuid	The GUID of the application running in the session instance. It uniquely identifies the application so that DirectPlay connects only to other computers running the same application. This member can be set to GUID_NULL to enumerate sessions for any application.
sessionName	Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use.
password	Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
flags	No flags are currently used by this method.

stopEnumGroupPlayers

public void stopEnumGroupPlayers();

Stops a group players enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Return Value:

No return value.

See Also: enumGroupPlayers

stopEnumGroups

public void stopEnumGroups();

Stops a group enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Return Value:

Returns no return value.

See Also: enumGroups

stopEnumPlayers

public void stopEnumPlayers();

Stops a players enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Return Value:

No return value.

See Also: enumPlayers

stopEnumServiceProviders

public void stopEnumServiceProviders();

Stops a service provider enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Return Value:

No return value.

See Also: enumServiceProviders

stopEnumSessions

public void stopEnumSessions();

Stops a session enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Return Value:

No return value.

See Also: enumSessions