Class DirectPlayLobby

public class DirectPlayLobby implements IDirectPlayLobby
{
  // Methods
  public DirectPlay2 connect();
  public DirectPlayLobby create(_Guid guid);
  public void createAddress(_Guid spGuid, _Guid addressTypeGuid,
        String addressString, byte[] addressData,
        int[] addressSize);
  public int createAddressSize(_Guid spGuid, _Guid addressTypeGuid,
        String addressString);
  public void enumAddress(IEnumAddressCallback callback,
        byte[] addressData, int addressSize, IUnknown context);
  public void enumAddressTypes(IEnumAddressTypesCallback callback,
        _Guid spGuid, IUnknown context, int flags);
  public void enumLocalApplications(
        IEnumLocalApplicationsCallback callback,
        IUnknown context, int flags);
  public void enumServiceProviders(
        IEnumServiceProvidersCallback callback, IUnknown context);
  public void getConnectionSettings(int applicationId,
        int[] connectionFlags, DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String[] sessionName, String[] password,
        String[] playerShortName, String[] playerLongName,
        _Guid guidSP, byte[] addressData, int[] addressSize);
  public int getConnectionSettingsAddressSize(int applicationId);
  public void receiveLobbyMessage(int applicationId, int[] flags,
        byte[] data, int[] dataSize);
  public void receiveLobbyMessageSize(int applicationId,
        int[] flags, int[] dataSize);
  public void runApplication(int[] applicationId,
        int connectionFlags, DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password,
        String playerShortName, String playerLongName,
        _Guid spGuid, byte[] addressData, int addressSize,
        int receiveEvent);
  public void sendLobbyMessage(int applicationId, byte[] data,
        int dataSize);
  public void setConnectionSettings(int applicationId,
        int connectionFlags, DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password,
        String playerShortName, String playerLongName,
        _Guid spGuid, byte[] addressData, int addressSize);
  public void setLobbyMessageEvent(int applicationId,
        int receiveEvent);
}

Methods

connect

public DirectPlay2 connect();

Connects an application to a session by using the connection data supplied by the lobby client in the runApplication method or by calling the setConnectionSettings method.

Return Value:

Returns a Microsoft® DirectPlay® object with the correct service provider and opens the correct session without prompting the user to complete any dialog boxes.

Remarks:

If this method fails with the DPERR_NOTLOBBIED error value, the application should perform the normal steps of calling enumServiceProviders, create, enumSessions and open. If it fails on any other error value, there is a problem connecting to the session.

Before calling this method, the application can examine the connection settings that will be used to start the application by using the getConnectionSettings method. The application can then modify these settings and set them by using the setConnectionSettings method.

create

public DirectPlayLobby create(_Guid guid);

Creates an instance of a IDirectPlayLobby object and attempts to initialize it.

Return Value:

Returns an DirectPlayLobby object.

Parameter	Description
guid	A globally unique identifier (GUID).

createAddress

public void createAddress(_Guid spGuid, _Guid addressTypeGuid,
        String addressString, byte[] addressData, int[] addressSize);

Creates a DirectPlay address when given a service provider-specific network address. The resulting address contains the GUID of the service provider and data that the service provider can interpret as a network address.

Return Value:

No return value.

Parameter	Description
spGuid	The address of the service provider GUID. (In C++, it is a reference to the GUID.)
addressTypeGuid	The address of a GUID identifying the specific network address type being used.
addressString	A buffer that the constructed DirectPlay address is to be written to.
addressData	A buffer containing the specific network address.
addressSize	The size of the DirectPlay address buffer. Before calling this method, the service provider must initialize addressSize to the size of the buffer. After the method has returned, this parameter will contain the number of bytes written to the address. If the buffer was too small (DPERR_BUFFERTOOSMALL), this parameter will be set to the size required to store the DirectPlay address.

createAddressSize

public int createAddressSize(_Guid spGuid, _Guid addressTypeGuid,
        String addressString);

Return Value:

Returns

Parameter	Description
spGuid	The address of the service provider GUID.
addressTypeGuid	The address of a GUID identifying the specific network address type being used.
addressString	A buffer in which the constructed DirectPlay address is to be written.

enumAddress

public void enumAddress(IEnumAddressCallback callback, byte[] addressData,
        int addressSize, IUnknown context);

Parses out sections from the DirectPlay address buffer.

Return Value:

No return value.

Parameter	Description
callback	The EnumAddressCallback function that will be called for each information section in the DirectPlay address.
addressData	The start of the DirectPlay address buffer.
addressSize	The size of the DirectPlay address.
context	The context that will be passed to the callback function.

enumAddressTypes

public void enumAddressTypes(IEnumAddressTypesCallback callback,
        _Guid spGuid, IUnknown context, int flags);

Enumerates all the address types that a given service provider needs to build the DirectPlay address.

Return Value:

No return value.

Parameter	Description
callback	The EnumAddressTypeCallback function that will be called for each address type for a service provider. If the service provider takes no address type, the callback will not be called.
spGuid	The GUID of the service provider, whose address types are to be enumerated.
context	The context that will be passed to the callback function.
flags	Reserved; the value must be zero.

enumLocalApplications

public void enumLocalApplications(IEnumLocalApplicationsCallback callback,
        IUnknown context, int flags);

Enumerates the applications that are registered with DirectPlay.

Return Value:

No return value.

Parameter	Description
callback	The EnumLocalApplicationsCallback function that will be called for each enumerated application.
context	The context passed to the callback function.
flags	Reserved; must be zero.

enumServiceProviders

public void enumServiceProviders(IEnumServiceProvidersCallback callback,
        IUnknown context);

Enumerates the DirectPlayLobby service providers installed on the system.

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 on the system.
context	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 enabled to use those service providers. For example, a TAPI service provider may be enumerated, even though the system may not have a modem installed.

getConnectionSettings

public void getConnectionSettings(int applicationId, int[] connectionFlags,
        DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid
        applicationGuid, String[] sessionName, String[] password, String[]
        playerShortName, String[] playerLongName, _Guid guidSP, byte[]
        addressData, int[] addressSize);

Retrieves all the information needed to start and connect an application. The data returned is the same data that was passed to the runApplication method by the lobby client or set by calling the setConnectionSettings method.

Return Value:

No return value.

Parameter	Description
applicationId	The application identifier.
connectionFlags	Indicates how the connection should be made. This may be one of the following: DPLCONNECTION_CREATESESSION Creates a new session as described in the session description. DPLCONNECTION_JOINSESSION Joins the existing session as described in the session description.
sessionDesc	A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this class will 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.
applicationGuid	The application GUID.
sessionName	The 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.
playerShortName	The short name that the player should be created with. This will be the name of the person registered in the lobby. The application can ignore this name.
playerLongName	The long name that the player should be created with.
guidSP	The GUID of the service provider used to connect to the session.
addressData	The information that the service provider needs to connect to a session.
addressSize	The address data size (in bytes).

getConnectionSettingsAddressSize

public int getConnectionSettingsAddressSize(int applicationId);

Retrieves the size of the buffer that contains the connection settings.

Return Value:

Returns the buffer size (in bytes).

Parameter	Description
applicationId	When called from a lobby client that communicates with several applications, this parameter identifies which application connection settings to retrieve.

receiveLobbyMessage

public void receiveLobbyMessage(int applicationId, int[] flags,
        byte[] data, int[] dataSize);

Retrieves the message sent between a lobby client application and a DirectPlay application. Messages are queued, so there is no danger of losing data if it is not read in time.

Return Value:

No return value.

Parameter	Description
applicationId	Identifies which application message to retrieve when called from a lobby client (that communicates with several applications). When called from an application (that communicates only with one lobby client), this parameter must be set to zero. This ID number is obtained by using the runApplication method.
flags	Flags indicating what type of message is being returned. This may be DPLAD_SYSTEM.
data	The message to be written. Set this parameter to NULL to request only the size of message. The lpdwDataSize parameter will be set to the minimum size required to hold the message.
dataSize	The size of the buffer before this method is called. After the method returns, this parameter will be set to the size, in bytes, of the message. If the buffer was too small (DPERR_BUFFERTOOSMALL), this parameter will be set to the minimum buffer size required.

receiveLobbyMessageSize

public void receiveLobbyMessageSize(int applicationId, int[] flags,
        int[] dataSize);

Retrieves the size of the message sent between a lobby client application and a DirectPlay application.

Return Value:

No return value.

Parameter	Description
applicationId	Identifies which application's message to retrieve when this method is called from a lobby client (that communicates with several applications).
flags	The flags indicating the type of message being returned.
dataSize	The size of the buffer before this method is called. After the method returns, dataSize will be set to the size (in bytes) of the message. If the buffer was too small (DPERR_BUFFERTOOSMALL), dataSize will be set to the minimum buffer size required.

runApplication

public void runApplication(int[] applicationId, int connectionFlags,
        DPSessionDesc sessionDesc, _Guid sessionGuid,
        _Guid applicationGuid, String sessionName, String password,
        String playerShortName, String playerLongName, _Guid spGuid, byte[]
        addressData, int addressSize, int receiveEvent);

Runs a DirectPlay application.

Return Value:

No return value.

Parameter	Description
applicationId	The application identifier.
connectionFlags	Indicates how the connection should be made. This parameter may be one of the following flags: DPLCONNECTION_CREATESESSION Creates a new session as described in the session description. DPLCONNECTION_JOINSESSION Joins the existing session as described in the session description.
sessionDesc	A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this class will 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.
applicationGuid	The application GUID.
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.
playerShortName	The short name that the player should be created with. This will be the name of the person registered in the lobby. The application can ignore this name.
playerLongName	The long name that the player should be created with.
spGuid	The GUID of the service provider used to connect to the session.
addressData	The information that the service provider needs to connect to a session.
addressSize	Address data size (in bytes).
receiveEvent	The event handle set when a message is received.

sendLobbyMessage

public void sendLobbyMessage(int applicationId, byte[] data, int dataSize);

Sends a message between the application and the lobby client.

Return Value:

No return value.

Parameter	Description
applicationId	Identifies which application to send a message to when called from a lobby client (that communicates with several applications). When called from an application (that communicates with only one lobby client), this parameter must be zero. This ID is obtained by using the runApplication method.
data	The message to send.
dataSize	The buffer size (in bytes).

setConnectionSettings

public void setConnectionSettings(int applicationId, int connectionFlags,
        DPSessionDesc sessionDesc, _Guid sessionGuid,
        _Guid applicationGuid, String sessionName, String password,
        String playerShortName, String playerLongName, _Guid spGuid, byte[]
        addressData, int addressSize);

Modifies the connection settings needed to start and connect an application.

Return Value:

No return value.

Parameter	Description
applicationId	When this method is called from a lobby client that communicates with several applications, applicationId identifies which application connection settings to retrieve.
connectionFlags	Indicates how the connection should be made. This parameter may be one of the following flags: DPLCONNECTION_CREATESESSION Creates a new session as described in the session description. DPLCONNECTION_JOINSESSION Joins the existing session as described in the session description.
sessionDesc	A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this class will 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.
applicationGuid	The application GUID.
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.
playerShortName	The short name that the player should be created with. This will be the name of the person registered in the lobby. The application can ignore this name.
playerLongName	The long name that the player should be created with.
spGuid	The GUID of the service provider used to connect to the session.
addressData	The information that the service provider needs to connect to a session.
addressSize	The address data size (in bytes).

setLobbyMessageEvent

public void setLobbyMessageEvent(int applicationId, int receiveEvent);

Registers an event that will be set when a lobby message is received. The application must call this method if it needs to synchronize with messages. The lobby client can call this method to change the events specified in the call to the runApplication method.

Return Value:

No return value.

Parameter	Description
applicationId	Identifies which application the event is associated with when called from a lobby client that communicates with several applications. When called from an application that communicates with only one lobby client, this parameter must be zero. This ID number is obtained from runApplication.
receiveEvent	The event handle set when a message is received.