[C++]

This tutorial pertains only to applications written in Visual Basic. See DirectPlay C/C++ Tutorials

[Visual Basic]

When the user has chosen a service provider and player name in the Multiple Player dialog and clicked OK, the Memory application initializes the selected connection. DirectPlay4.InitializeConnection binds the connection to DirectPlay, so that subsequent method calls go to that connection, but it does not actually establish the physical connection. That is done when sessions are enumerated.

When an attempt is made to enumerate sessions on the connection, some service providers (such as the modem service provider) present dialog boxes asking for further information in order to establish the physical connection. If users wish to create a new game rather than joining an existing one, they can simply cancel out of these dialogs.

Memory attempts to enumerate sessions even though the user might not be interested in viewing existing sessions but would rather go directly to creating a new one. In your application you might want to do things differently and not call DirectPlay4.GetDPEnumSessions unless the user requests a list of existing sessions. Not calling this method can simplify things for users in certain cases. For example, the modem service provider has two separate dialog boxes, one for dialing and one for answering. A player creating a new game is not interested in the dialing prompt, because the host of a modem game always waits for the other player to call in. Skipping session enumeration and going straight to DirectPlay4.Open will ensure that the host never has to see the dialing prompt.

The following procedure in frmMultiplayer initializes the selected connection and puts any available sessions in a list box to be displayed in the next dialog box:

Private Sub cmdOK_Click()
 
  Dim CIndex As Long
  Dim ConnectionMade As Boolean
  Dim objDPAddress As DirectPlayAddress
 
  CIndex = lstConnections.ListIndex + 1

Remember, enumeration collections are 1-based, but lists in list boxes are 0-based, so the index into the collection has to be adjusted.

The application now gets the DirectPlay address for the connection and initializes it:

  On Error GoTo INITIALIZEFAILED
  Set objDPAddress = gObjEnumConnections.GetAddress(CIndex)
  Call gObjDPlay.InitializeConnection(objDPAddress)
  On Error GoTo 0
  

The next call is discussed in more detail later.

  ConnectionMade = frmSessions.UpdateSessionList

The form is then closed, and the user is shown a new one that contains the list of sessions as well as buttons allowing the user to join or create a session.

  If ConnectionMade Then
    Hide
    frmSessions.Show
  Else
    InitDPlay
  End If
  Exit Sub 
  ' Error handlers
 
INITIALIZEFAILED:
  If Err.Number <> DPERR_ALREADYINITIALIZED Then
    MsgBox ("Failed to initialize connection.")
    Exit Sub
  End If
  
End Sub

Session enumeration is done in the following function, which is also used to update the session list as new sessions become available or old ones disappear:

Public Function UpdateSessionList() As Boolean
  
  Dim SessionCount As Integer
  Dim X As Integer
  Dim SessionData As DirectPlaySessionData
  Dim Details As String
  
  ' Delete the old list
  lstSessions.Clear
  
  Set SessionData = gObjDPlay.CreateSessionData
  

The DirectPlaySessionData object describes the sessions to be enumerated. Because Memory is not interested in sessions of other applications, it specifies its privately defined application GUID (in string form). If enumeration was to be restricted to sessions with a particular password, the password would also be set in the session description here.

  Call SessionData.SetGuidApplication(AppGuid)
  Call SessionData.SetSessionPassword("")
  

The call to DirectPlay4.GetDPEnumSessions specifies that only available sessions are wanted, not those that have reached their maximum number of players or otherwise can't be joined:

  On Error GoTo USERCANCEL
  Set gObjDPEnumSessions = gObjDPlay.GetDPEnumSessions(SessionData, _
          0, DPENUMSESSIONS_AVAILABLE)
  On Error GoTo 0

Note that the method fails if the user has canceled out of any service provider dialogs. The function assumes that the player might want to create a new session, so it does not treat this error as fatal.

If enumeration succeeds, the application now uses the DirectPlayEnumSessions object to extract information about each session, including its name, the current number of players, and the maximum number of players. This information is combined in a string that is then put in the list box:

  On Error GoTo ENUM_ERROR
  SessionCount = gObjDPEnumSessions.GetCount
  For X = 1 To SessionCount
    Set SessionData = gObjDPEnumSessions.GetItem(X)
    Details = SessionData.GetSessionName & " (" _
            & SessionData.GetCurrentPlayers _
            & "/" & SessionData.GetMaxPlayers & ")"
    Call lstSessions.AddItem(Details)
  Next X

The rest of the function, not shown here, updates the interface and handles errors.

Next: Step 3: Create or Join a Session