ppt title

1
(No Transcript)
2
DirectPlay Lobby Workshop Rod
Toll Development LeadDirectPlay
Voice/Lobby Microsoft Corporation
3
Overview

• DirectPlay Lobby
• Feature Overview
• Lobby Basics
• Building Lobby Clients
• Enabling Lobby Launching
• Advanced Lobbying
• Matchmaking Reference Procedure

4
DirectPlay Lobby

• Feature Overview

5
The Goals

• Enable robust application launching capabilities
• Require minimal custom code for application and
  launch-service developers

6
Lobby Customers

• Applications / Lobbied Applications
• App that wants to be launched
• e.g., Age of Empires I/II, MechCommander,
  Starlancer, Jedi Knight, Sacrifice, Giants
• Launchers / Lobby Clients
• App that wants to launch applications.
• e.g., Messenger, GameVoice, The Zone

7
Lobby Architecture

• Portions in white are provided by DirectPlay Lobby

8
DirectPlay Lobby Features

• Features of DirectPlay Lobby
• Game registration
• Generic game launching
• Session and launch parameter specification
• Post-launch IPC
• Post-launch connections

9
Game Registration

• Game registration database
• Games uniquely identified by GUID
• Application location and parameters
• Registration
• Register during install
• De-register during uninstall

10
Generic Game Launching

• API for developers to enable launching
• Registration to enable discovery
• Specification of launch command-line
• Reduce or eliminate per launcher code
• API for launchers to launch games
• Discovery of installed applications
• Generic launch and process monitoring
• Reduce or eliminate per title code

11
Launch Parameters

• Specification of session information
• Session name
• Maximum players
• Address of session
• Player name
• All information commonly required for DirectPlay8
  

12
Post Launch IPC

• Robust communication system
• Arbitrarily sized user data
• Target individual or all connections
• Lobby system messages
• Status change messages
• Connection information updates
• Target individual or all connections

13
Post Launch Connection

• Connections to running applications
• Enumeration of running applications
• Establishment of connection
• Multiple connections supported
• Applications control availability

14
What Isnt Provided?

• Lobby is not a matchmaking system
• One component in a complete system
• Several existing providers of matchmaking
  (Messenger, The Zone)
• Does not provide inter-node synchronization
• Lobby is not a chat system
• No Inter-node communications
• DirectPlay can provide this functionality

15
Lobby Basics

• Getting Started With The Lobby

16
Using Lobby

• Using Lobby
• Objects are provided by DPNLOBBY.DLL
• Definitions are in DPLOBBY8.H
• NO .lib file required
• Creation
• COM should be initialized for multithreaded
  apartment
• Create objects using CoCreateInstance
• DirectPlay8LobbyCreate no longer supported in
  DirectX 8.1

17
Object Model

• Lobbied applications
• CLSID_DirectPlay8LobbiedApplication w/
  IID_IDirectPlay8LobbiedApplication
• Lobby clients API
• CLSID_DirectPlay8LobbyClient w/
  IID_IDirectPlay8LobbyClient
• Visual Basic also supported through DirectX for
  Visual Basic

18
Push vs. Pull

• Lobby uses a push model for messages
• Messages are indicated to the application through
  application callback function
• Messages can be indicated at any time
• Messages may not be indicated on app thread.
  (Thread WILL have COM)
• Callback function must be reentrant
• Callback function uses same signature as
  DirectPlay8 and DirectPlay Voice

19
Callback Function

• HRESULT WINAPI Callback(PVOID pvUserContext,
  DWORD dwMessageType, PVOID pMessage )
• pvUserContext app supplied context value
• dwMessageType message type (DPL_MSGID_)
• pMessage pointer to structure describing
  message (DPL_MSG_)

20
Lobby Connections

• Lobby clients can connect to multiple lobbied
  applications
• Lobbied applications can be connected to multiple
  lobby clients
• Each connection is identified by a DPNHANDLE
• DPNHANDLE values are unique within process ONLY
• If app or launcher exits, connection(s) are
  automatically cleaned up

21
Context Values

• Each connection has an associated context value
• Value is set when connection is created or
  indicated
• Connection messages ARE matched
• No way to retrieve value outside of messages

22
Connection Settings

• Each connection has a connection settings
  structure associated with it
• Set during the call to LaunchApplication
• Can be updated by calling SetConnectionSettings
  for a connection
• Other end receives message that includes new
  settings
• Settings can be retrieved by GetConnectionSettings

23
Sending User Data

• Lobby Clients and Lobbied Applications can
  exchange messages
• Always guaranteed.
• Upper limit on message size (65535 bytes)
• If no space in IPC Queue, will block. (timeout)
• Target can be either a specific connection
  (DPNHANDLE) or DPLHANDLE_ALLCONNECTIONS
• Target will receive DPL_MSGID_RECEIVE

24
Common System Messages

• Common messages between launchers and
  applications
• DPL_MSGID_DISCONNECT Connection dropped
• DPL_MSGID_CONNECTION_SETTINGS Connection
  settings updated
• DPL_MSGID_RECEIVE User data is received

25
DPL_MSGID_DISCONNECT

• Message received when connection closed because
• Partner has exited without cleanup
• Partner has closed connection
• Object cleanup
• Guaranteed to receive one of these for each
  successful connection
• No more messages from this connection after this
  is indicated

26
DPL_MSGID_DISCONNECT

• Message contains
• DPNHANDLE of connection
• The reason for the disconnect
• DPNERR_CONNECTIONLOST partner exited
  unexpectedly
• DPN_OK partner closed connection
• Connection context. Safe to destroy associated
  memory

27
DPL_MSGID_CONNECTION_SETTINGS

• Received when settings updated by partner via
  SetConnectionSettings
• Settings are always mirrored between partners
• Once indicated GetConnectionSettings will reflect
  new settings
• Sent on a per connection basis

28
DPL_MSGID_CONNECTION_SETTINGS

• Message contains
• DPNHANDLE of connection
• Pointer to connection settings. (Only valid
  during callback function). DEEP COPY!
• Connection context

29
DPL_MSGID_RECEIVE

• Used to indicate receive of app message
• Message contains
• DPNHANDLE of connection
• Pointer to message contents. DEEP COPY!
• Connection context

30
Message Guarantees

• Guaranteed behavior
• Only indicating one message per connection at any
  time
• No messages for connection AFTER
  DPL_MSGID_DISCONNECT
• One disconnect message per connection

31
Lobby Clients

• Launcher Procedures

32
Launching An Application

• Procedure to launch an application
• Create and initialize object
• Enumerate available applications
• Choose application to launch
• Choose connection method
• Setup launch parameters
• Execute launch
• Monitor status

33
Create And Initialize Object

• Create and Initialize Object
• Ensure COM initialized for multithreaded
  apartment
• CoCreateInstance object w/CLSID_DirectPlay8LobbyCl
  ient and IID_IDirectPlay8LobbyClient
• Initialize object with callback function
• Only ONE lobby client object per process

34
Create And Initialize Object

• hr CoInitializeEx(NULL, COINIT_MULTITHREADED)
• If( FAILED( hr ) ) // Handle Error
• hr CoCreateInstance( CLSID_DirectPlay8LobbyClien
  t, NULL,
• CLSCTX_INPROC_SERVER,
• IID_IDirectPlay8LobbiedApplication,
• (LPVOID) g_pLobbyClient
  )
• if( FAILED( hr ) ) // Handle Error
• hr g_pLobbyClient-Initialize(pContextValue,
  MyLobbyCallback, 0 )
• if( FAILED( hr ) ) // Handle Error

35
Enumerate Available Apps

• Enumerate available applications
• Returns list of registered applications
• Standard Windows enumeration call, determine
  size, allocate and re-call
• Optional if you know GUID of app
• For each application
• Application GUID and name.
• How many copies are currently running
• How many copies are available for connecting

36
Enumerate Available Apps

• DWORD dwSize 0, dwPrograms 0
• BYTE pData NULL
• hr g_pLobbyClient-EnumLocalPrograms( NULL,
  pData, dwSize, dwPrograms, 0 )
• if( hr ! DPNERR_BUFFERTOOSMALL FAILED(hr) )
  // Handle error
• pData new BYTEdwSize
• hr g_pLobbyClient-EnumLocalPrograms( NULL,
  pData, dwSize, dwPrograms, 0 )
• if( FAILED( hr ) ) // Handle error
• // dwSize size of data, dwPrograms of apps
  registered
• // pData recast array of DPL_APPLICATION_INFO
• // dwSize ! dwPrograms sizeof(
  DPL_APPLICATION_INFO )
• // Need to delete pData when done with data

37
Choose Connection Method

• Choose type of connection in dwFlags of
  DPL_CONNECT_INFO structure
• DPLCONNECT_LAUNCHNEW Always launch a new
  instance
• DPLCONNECT_LAUNCHNOTFOUND Launch if none
  available for connect
• Neither Connect to existing or fail
• Most applications will specify DPLCONNECT_LAUNCHNE
  W flag

38
Setup Connect Parameters

• Setup DPL_CONNECT_INFO structure.
• Zero out structure, set dwSize
• Specify flags to control connect type
• Specify connection settings. (optional)
• Specify connect data. (optional)
• Values specified are indicated with
  DPL_MSGID_CONNECT message on applications

39
Setup Connect Parameters

• // Setup connect parameters
• ZeroMemory( dplConnectInfo, sizeof(DPL_CONNECT_IN
  FO) )
• dplConnectInfo.dwSize sizeof(DPL_CONNECT_INFO)
• dplConnectInfo.pvLobbyConnectData NULL
• dplConnectInfo.dwLobbyConnectDataSize 0
• dplConnectInfo.dwFlags 0 // Launch unless one
  available
• dplConnectInfo.pdplConnectionSettings
  dplConSettings
• if( bLaunchNew ) // If we want to force new
  launch
• dplConnectInfo.dwFlags DPLCONNECT_LAUNCHNEW
• if( bLaunchNotFound ) // If we want to launch if
  not found
• dplConnectInfo.dwFlags DPLCONNECT_LAUNCHNOTFOU
  ND
• // Specifies which app to connect/launch
• dplConnectInfo.guidApplication g_guidApp

40
Execute Launch

• Call ConnectApplication() to execute launch.
• Application will be launched and connection
  established before return
• Specify context value for connection
• Handle for connection returned in parameter
• Timeout can be specified
• Result of launch in function call return

41
Execute Launch

• // Execute launch
• hr g_pLobbyClient-ConnectApplication(
• dplConnectInfo, // Connection Info
• pvConnectionContext, // Connect context value
• dplhApplication, // To receive connect
  handle
• dwTimeout, // timeout for launch
• 0 ) // Flags field
• if( hr DPNERR_NOCONNECTION )
• // Launch or connection failed
• else if( hr DPNERR_TIMEDOUT )
• // Timed-out establishing connection (app
  crash?)
• else if( FAILED( hr ) )
• // Other failure

42
Monitor Status

• Monitor message callbacks to watch for
  indications
• DPL_MSGID_RECEIVE if application data sent
• DPL_MSGID_CONNECTION_SETTINGS if application
  updates connection settings
• DPL_MSGID_SESSION_STATUS if application indicates
  status

43
DPL_MSGID_SESSION_STATUS

• Indicated when application updates status with
  UpdateStatus()
• DPNHANDLE of connection
• New status
• Connection context value
• Possible status values indicated by
  DPLSESSION_XXXX defines
• Can be automated with DirectPlay8

44
Desired Post Launch Behavior

• If client successfully establishes connection or
  starts hosting
• DPL_MSGID_CONNECTION_SETTINGS is received by
  client. This contains updated and complete
  session information
• DPL_MSGID_SESSION_STATUS with DPLSESSION_CONNECTED
  status
• Failure to connect
• DPL_MSGID_SESSION_STATUS with DPLSESSION_COULDNOTC
  ONNECT status

45
Desired Post Launch Behavior

• Host migration
• If host migrated to the application
  DPL_MSGID_SESSION_STATUS w/ a DPLSESSION_HOSTMIGRA
  TEDHERE
• If host migrates, but not to the application
  DPL_MSGID_SESSION_STATUS w/a DPLSESSION_HOSTMIGRAT
  ED
• Behavior can be automatic by using RegisterLobby
  with DirectPlay8

46
Ending A Session

• Call ReleaseApplication() to terminate
  connections
• Specify DPNHANDLE of connection to close
• Specify DPLHANDLE_ALLCONNECTIONS to close all
  connections
• When connection terminates, DPL_MSGID_DISCONNECT
  is indicated
• Release() object when done

47
Lobbied Applications

• Enabling Your Application For Launching

48
Ripple Launching

• Ripple Launching is supported
• Game application is executed by another
  application (Ripple Launcher)
• Ripple Launcher usually provides some kind of
  decryption and copy protection

49
Lobby Launching

• When lobby launching an application
• Has DPLIDXXXX added to the command-line
• This parameter is required by lobby to establish
  connection
• Ripple Launchers must pass this command-line
  through to application

50
Enabling For Launch

• Procedure to enable application for launch
• Register application
• Create and initialize object. Check to see if
  lobby launched
• Start transport session
• Update launcher with status changes
• Register lobby interface with DirectPlay8 OR
• Update launcher with status changes
• Monitor status

51
Registering Applications

• To enable lobby launching, application must be
  registered
• Use the API calls to register, do not write to
  registry directly
• Format of entries may change
• Location of entries may change
• Ensures compatibility going forward
• Register during application setup
• Register with UNIQUE app guid

52
Registering Applications

• Parameters for registration
• App Name Name displayed by Enum
• Exe Filename Filename extension
• Exe Path Path to file (no trailing \)
• Launcher Params NULL unless Ripple
• Ripple Launching
• Launcher Name Filename extension
• Launcher Path Path to filename

53
Registering Applications

• DPL_PROGRAM_DESC dplDesc
• // Setup registration entry
• ZeroMemory(dplDesc, sizeof(DPL_PROGRAM_DESC))
• dplDesc.dwSize sizeof(DPL_PROGRAM_DESC)
• dplDesc.guidApplication g_guidApp // MUST be
  unique to app
• dplDesc.pwszApplicationName g_szAppName //
  Name returned in enums
• dplDesc.pwszCommandLine g_szCommandLine //
  Command-Line
• dplDesc.pwszDescription g_szDesc //
  Description of app
• dplDesc.pwszExecutableFilename g_szEXE //
  filename of app
• dplDesc.pwszExecutablePath g_szEXEPath // path
  to filename
• dplDesc.pwszLauncherFilename g_szLauncherEXE
  // launcher filename
• dplDesc.pwszLauncherPath g_szLauncherPath //
  path to launcher
• hr g_pLobbyApp-RegisterProgram( dplDesc, 0 )
• if( FAILED( hr ) ) // Handle Error

54
Create And Initialize Object

• Create and Initialize Object
• Ensure COM initialized for multithreaded
  apartment
• CoCreateInstance object w/CLSID_DirectPlay8Lobbied
  Application and IID_IDirectPlay8LobbiedApplicatio
  n
• Initialize object with callback function
• If lobby launch, connection is established before
  return
• Only ONE lobbied application object per process

55
Create And Initialize Object

• hr CoInitializeEx(NULL, COINIT_MULTITHREADED)
• If( FAILED( hr ) ) // Handle Error
• hr CoCreateInstance( CLSID_DirectPlay8LobbiedApp
  lication, NULL,
• CLSCTX_INPROC_SERVER,
• IID_IDirectPlay8LobbiedApplication,
• (LPVOID) g_pLobbyClient
  )
• if( FAILED( hr ) ) // Handle Error
• hr g_pLobbyClient-Initialize( pContextValue,
  MyLobbyCallback,
• dpnConnectHandle, // Receives connect handle
• 0 )
• if( FAILED( hr ) ) // Handle Error
• If( dpnConnectHandle ) // App was lobby
  launched

56
Start Transport Session

• Look at parameters to determine what transport
  actions to take
• dwFlags field of DPL_CONNECTION_SETTINGS
  structure
• DPLCONNECTSETTINGS_HOST indicates that host
  should be initiated
• If connecting
• Address may not contain a port
• Enumerate address to discover port
• HANDLE THIS CASE!

57
Update Launcher w/Status

• DirectPlay8 applications call IDirectPlay8XXXXRe
  gisterLobby()
• Specify connection handle to use
• Specify lobby object to use
• Must be called BEFORE Host() or Connect()
• Completely automates keeping the lobby client
  informed

58
Update Launcher w/Status

• Non-DirectPlay applications can manually provide
  updates
• Update connection settings with full values and
  call SetConnectionSettings
• Status Updates are sent using UpdateStatus()
• Send status messages as transport status changes
• Specify either connection or all connections

59
Monitor Status

• Monitor message callbacks to watch for
  indications
• DPL_MSGID_RECEIVE if application data sent
• DPL_MSGID_CONNECTION_SETTINGS if application
  updates connection settings
• DPL_MSGID_CONNECT if connection is established

60
DPL_MSGID_CONNECT

• Indicated to application when connection
  established
• Indicated for launch and post-launch connections
• Provides description of new connection
• DPNHANDLE of new connection
• Connection settings. DEEP COPY!
• Lobby connect data
• Set pvConnectionContext to set connections user
  context value

61
Ending A Session

• Call Close() to terminate all active connections
• No method to close an individual connection
• When connection terminates, DPL_MSGID_DISCONNECT
  is indicated
• Release() object when done

62
Unregistering Applications

• Removes application from list of registered apps
• Use the API calls to unregister, do not remove
  registry entries directly
• Format of entries may change
• Location of entries may change
• Ensures compatibility going forward
• Unregister during application uninstall

63
Unregistering Applications

• // Unregister application
• hr g_pLobbyApp-UnRegisterProgram( g_guidApp,
  0 )
• If( FAILED( hr ) )
• // Handle Error

64
Advanced Lobby

• Extreme Lobby Development

65
Enabling Post Launch Connects

• Lobbied applications can enable post launch
  connections
• Call SetAppAvailable
• Flags app as available for connections
• After connect state is reset unless
  DPLAVAILABLE_ALLOWMULTIPLECONNECT is specified
• Connections indicated as DPL_MSGID_CONNECT

66
Disable Parameter Validation

• Parameter validation can be disabled
• Specify DPLINITIALIZE_DISABLEPARAMVAL on
  Initialize call
• Disables parameter logic validation but not state
  validation
• Not recommended until application is near the end
  of development

67
Matchmaking Service

• Reference Architecture

68
Matchmaker Architecture
69
Matchmaking Architecture

• Service commands client to launch
• Lobby launch of host is executed
• Settings from launch sent to client
• Settings from launch sent to service
• Service commands client(s) to launch
• Lobby launch of client(s) is executed
• Client establishes transport connection to host
• Settings from launch sent to service

70
Further Information

• Where To Go From Here

71
DirectX SDK

• SDK documentation
• Updated for DirectX 8.1 with more detail
• Step by step tutorials
• Sample applications
• All DirectPlay samples are lobby enabled
• LobbyClient is sample lobby client
• Tutorial applications
• Command-line lobby enabled application
• LobbyLaunch.cpp