Previous
Microsoft Packages
Index
Next
| Package com.ms.com.directX |
Previous |
Microsoft Packages |
Index |
Next |
Applications use the methods of the dPlay class to create DirectPlay objects and work with system-level variables.
public class dPlay implements IdPlay
{
public void InternalSetObject(IUnknown lpdd);
public IUnknown InternalGetObject();
public dPlay Create(GuidData g, IUnknown punk);
public void AddPlayerToGroup(int v1, int v2);
public void Close();
public int CreatePlayer(String v2, String v3);
public int CreateGroup(String v2, String v3);
public void DeletePlayerFromGroup(int v1, int v2);
public void DestroyPlayer(int v1);
public void DestroyGroup(int v1);
public void EnableNewPlayers(int onoff);
public void EnumGroupPlayers(int id, IEnumPlayersCallback fn, IUnknown args, int val);
public void EnumGroups(int fl, IEnumPlayersCallback fn, IUnknown args, int val);
public void EnumPlayers(int fl, IEnumPlayersCallback fn, IUnknown args, int val);
public void EnumSessions(DPSessionDesc s, int fl, IEnumSessionsCallback fn, IUnknown args, int val);
public void EnumServiceProviders(IEnumDPCallback fn, IUnknown lpargs);
public void GetCaps(DPCaps v1);
public int GetMessageCount(int id);
public void GetPlayerCaps(int id, DPCaps v2);
public String GetPlayerFriendlyName(int id);
public String GetPlayerFormalName(int id);
public void Initialize(GuidData g);
public void Open(DPSessionDesc desc);
public int ReceiveSize(int flags);
public void Receive(PlayerIDs desc, int flags, int[] buf, int size);
public void SaveSession(String name);
public void Send(int id1, int id2, int v3, int[] v4, int v5);
public void SetPlayerName(int id1, String v2, String v3);
}
The methods can be organized into the following groups:
| Creation | Create |
| Group management | AddPlayerToGroup |
| CreateGroup | |
| DeletePlayerFromGroup | |
| DestroyGroup | |
| EnumGroupPlayers | |
| EnumGroups | |
| Message management | GetMessageCount |
| Receive | |
| ReceiveSize | |
| Send | |
| Player management | CreatePlayer |
| DestroyPlayer | |
| EnumPlayers | |
| GetPlayerCaps | |
| GetPlayerFormalName | |
| GetPlayerFriendlyName | |
| SetPlayerName | |
| Session management | Close |
| EnumSessions | |
| EnumServiceProviders | |
| GetCaps | |
| Open | |
| SaveSession |
public void AddPlayerToGroup(int v1, int v2);Adds an existing player to an existing group.
Return Value:
No return value.
Parameter Description v1 Group ID of the group to be augmented. v2 Player 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_ADDPLAYERTOGROUP system message will be generated and sent to all the other players.
See Also: CreateGroup, DeletePlayerFromGroup, DPMSG_ADDPLAYERTOGROUP
public void Close();Closes a previously opened session.
Return Value:
No return value.
Remarks:
All locally created players will be destroyed, with corresponding DPSYS_DESTROYPLAYERORGROUP system messages sent to other session participants. However, no groups will be destroyed (use DestroyGroup to destroy the group).
See Also: DestroyPlayer, DPMSG_DESTROYPLAYERORGROUP, Open
public dPlay Create(GuidData g, IUnknown punk);Creates a DirectPlay object.
Return Value:
Returns the dPlay object if successful; null otherwise.
Parameter Description g A GuidData object that specifies the globally-unique identifier (GUID) that represents the service provider that should be created. punk Reserved; must be null. 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
public int CreateGroup(String v2, String v3);Creates a logical group of players in the current session.
Return Value:
Returns a unique DirectPlay ID that identifies the new group.
Parameter Description v2 The formal name of the group. Use null to indicate that the group has no formal name. v3 The friendly name of the group. Use null to indicate that the group has no friendly name. 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 IDs 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
public int CreatePlayer(String v2, String v3);Creates a local player for the current session.
Return Value:
Returns a unique DirectPlay ID that identifies the new player.
Parameter Description v2 The formal name of the player. Use null to indicate that the player has no formal name information. v3 The friendly name of the player. Use null to indicate that the player has no friendly name. 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 creation (see SetPlayerName). The names in v2 and v3 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
public void DeletePlayerFromGroup(int v1, int v2);Removes a player from a group.
Return Value:
No return value.
Parameter Description v1 Group ID of the group to be adjusted. v2 Player 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
public void DestroyGroup(int v1);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 v1 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, then a DPSYS_DESTROYPLAYERORGROUP system message.
See Also: CreateGroup, DPMSG_DESTROYPLAYERORGROUP
public void DestroyPlayer(int v1);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 it belonged. The player ID will not be reused during the current session.
Return Value:
No return value.
Parameter Description v1 The player 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, then a DPSYS_DESTROYPLAYERORGROUP system message.
See Also: CreatePlayer, DPMSG_DESTROYPLAYERORGROUP
public void EnableNewPlayers(int onoff);Enables or disables the addition of new players to a group.
Return Value:
No return value.
Parameter Description onoff Set to TRUE to enable, FALSE to disable.
public void EnumGroupPlayers(int id, IEnumPlayersCallback fn, IUnknown args, int val);Enumerates all of the players of a particular group existing in the current session.
Return Value:
No return value.
Parameter Description id The Group ID whose players are to be enumerated. fn Callback interface that contains the callback function to be called for every player in the group. args A caller-defined context that is passed to each enumeration callback. val Flags to pass to the callback function. Remarks:
By default, this method will enumerate 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
public void EnumGroups(int fl, IEnumPlayersCallback fn, IUnknown args, int val);Enumerates the groups available to a session.
Return Value:
No return value.
Parameter Description f1 DirectPlay session instance of interest. This parameter must be set to null unless the DPENUMPLAYERS_SESSION flag is specified. fn Callback interface that contains the callback function to be called for every group in the session. args A caller-defined context that is passed to each enumeration callback. val 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
public void EnumPlayers(int fl, IEnumPlayersCallback fn, IUnknown args, int val);Enumerates the players in a session.
Return Value:
No return value.
Parameter Description f1 DirectPlay session instance of interest. This parameter must be set to null unless the DPENUMPLAYERS_SESSION flag is specified. fn Callback instance that contains the callback function that will be called for every group in the session. args A caller-defined context that is passed to each enumeration callback. val One or more values of 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, 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: CreatePlayer, DestroyPlayer, EnumSessions
public void EnumSessions(DPSessionDesc s, int fl, IEnumSessionsCallback fn, IUnknown args, int val);Enumerates the sessions available to this DirectPlay object.
Return Value:
No return value.
Parameter Description s 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, then the szPassword field should be set accordingly. f1 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. fn Callback interface that contains the callback function to be called for each DirectPlay session responding. args A user-defined context that is passed to each enumeration callback. val A value of 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 them 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 using the DPESC_TIMEDOUT flag. At this point, you may choose to continue the enumeration by setting f1 to a new value and returning TRUE, or returning FALSE 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.
Normally, 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. Note 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
public void EnumServiceProviders(IEnumDPCallback fn, IUnknown lpargs);Enumerates the DirectPlay service providers installed on the system.
Return Value:
No return value.
Parameter Description fn The IEnumDPCallback interface that contains the callback function to be called with a description of each DirectPlay service provider interface installed in the system. lpargs 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.
public void GetCaps(DPCaps v1);Obtains the capabilities of this DirectPlay object.
Return Value:
No return value.
Parameter Description v1 A DPCaps object that receives the capabilities of the DirectPlay object. The dwSize field of the DPCaps object must be filled in before using GetCaps. 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: DPCaps, GetPlayerCaps, Send
public int GetMessageCount(int id);Queries for the number of messages in the receive queue for a specific local player.
Return Value:
Returns the message count.
Parameter Description id Player ID for which the message count is requested. The player must be local. See Also: Receive
public void GetPlayerCaps(int id, DPCaps v2);Obtains the current capabilities of a specified player.
Return Value:
No return value.
Parameter Description id Player ID for which the capabilities should be computed. v2 A DPCaps object that receives the capabilities. The dwSize field of the DPCaps object must be filled in before using GetPlayerCaps. Remarks:
The difference between this method and GetCaps is that this method returns the capabilities of the requested player and GetCaps returns the capabilities of the current session.
public String GetPlayerFormalName(int id);Obtains the formal name associated with a player.
Return Value:
Returns the name.
Parameter Description id Player ID number for which the name information is being requested. See Also: SetPlayerName
public String GetPlayerFriendlyName(int id);Obtains the friendly name associated with a player.
Return Value:
Returns the name.
Parameter Description id Player ID number for which the name information is being requested. See Also: SetPlayerName
public void Initialize(GuidData g);Initializes the dPlay object.
Return Value:
No return value.
Parameter Description g The GUID used as the interface identifier. Remarks:
Since the DirectPlay object is initialized when it is created, calling this method will always result in no action.
public void Open(DPSessionDesc desc);Establishes a gaming session instance.
Return Value:
No return value.
Parameter Description desc The DPSessionDesc object describing the session to be created or joined. 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 new players are disabled, joining is disabled, or the player limit has been reached will result in no action.
See Also: Close, EnumSessions
public void Receive(PlayerIDs desc, int flags, int[] buf, int size);Retrieves a message from the message queue.
Return Value:
No return value.
Parameter Description desc A PlayerIDs object that receives the player ID of the sender and/or receiver of the message. If the DPRECEIVE_FROMPLAYER flag is specified, the sender field in this object must be initialized with the player ID before calling this method. If the DPRECEIVE_TOPLAYER flag is specified, the receiver field must be initialized with the player ID before calling this method. 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. buf Array variable that receives the message data. size The length of the array assigned to the buf parameter. Remarks:
Any message received from player ID DPID_SYSMSG is a system message generated by the host. For such messages, the application should interpret buf 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 and if data corruption is detected, it will either be thrown away (if it was sent non-guaranteed) or it will be retransmitted (if it was sent guaranteed).
See Also: Send
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.
public void SaveSession(String name);Saves the current session.
Return Value:
No return value.
Parameter Description name The name to associate with the saved session.
public void Send(int id1, int id2, int v3, int[] v4, int v5);Sends messages to other players, to a group of players, or to all players in the session.
Return Value:
No return value.
Parameter Description id1 Player ID of the sending player. The player ID must correspond to one of the local players on this machine. id2 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, then this parameter must be a player ID. v3 One value of DPSEND_ type, indicating how the message should be sent. If this parameter is set to 0, the message is sent non-guaranteed and at normal priority. v4 Array variable that contains the data being sent. Set to null if there is no actual message to send. v5 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 an Lock / Unlock or 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 machine.
Messages can be sent guaranteed or non-guaranteed. By default, messages are sent non-guaranteed, which means that DirectPlay does no verification that the message reached the intended recipient. Sending a guaranteed message takes much longer, a minimum of 2 to 3 times longer than a non-guaranteed 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 non-guaranteed) or it will be retransmitted (if it was sent guaranteed).
Note In this version of DirectPlay, 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, then the DPSEND_GUARANTEED flag will be ignored and the message will be sent non-guaranteed. The next version of DirectPlay will implement guaranteed delivery on non-guaranteed 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.
See Also: Receive
public void SetPlayerName(int id1, String v2, String v3);Sets the name of the player after it has been changed. 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 id1 Player ID for which data is being sent. v2 The formal name for the player. Use null if the player has no formal name. v3 The friendly name for the player. Use null if the player has no friendly name. See Also: DPMSG_SETPLAYERORGROUPNAME, GetPlayerFormalName, GetPlayerFriendlyName, Send
