documentation/status/directplay - wine - Git at Google

 This file contains information on the implementation of the direct play
 and direct play lobby features. There's lots to do and I'm not exactly
 implementing it overnight! Please lend a hand.

 Most methods and APIs are but stubs at this point. Examine the code
 to see what has been implemented. Use -debugmsg +dplay to get a
 reasonably thourough description of what's going on.

 Associated DirectX user header files are include/dplay.h, include/dplobby.h.

 Implementation of the DPLAY and DPLAYX dlls are both in the dlls/dplayx
 directory. Here's a brief description of the function of each of the files in that
 directory:

 dplay.c: Implementation of all the direct play object interfaces.

 dplobby.c: Implementation of all the direct play lobby interfaces.

 dpclassfactory.c: Implementation of the COM class factory which can create either
                   direct play lobby or direct play lobby interfaces.

 dpinit.h: Header file so that dpclassfactory.c can access dplay and dplobby query
           functions. Shouldn't be included by anything else.

 dplayx_global.h,
 dplayx_global.c: Implementation of all things which are associated with dplay on
                  the computer - ie shared resources and such. Methods in this
                  compilation unit should not call anything out side this unit
                  excepting base windows services and an interface to start the
                  messaging thread.

 name_server.h,
 name_server.c: Implementation of all things which are associated with the name
                server functionality

 dplayx_main.c: LibMain executed for loading and unloading the dll. This will make
                the call to dplayx_global.c to request initialization and destruction
                of any global data.

 dplayx_queue.h: Linked list implementation for dplay/dplobby. Based off of the BSD
                 version found in <sys/queue.h>

 dplayx_messages.h,
 dplayx_messages.c: Messaging interface required for both DirectPlay and
                    DirectPlayLobby.

 Presently the architectural relationship between this files is a little shakey, but
 isn't so sufficiently bad that it needs fixing yet.

 I think I can safely say that any application which requires direct play
 or direct play lobby will not work at this point. Priority will be to get
 examples from the sdk running. Once they're at least partially working, I can
 get down to trying to get some of the games working.

 However, now that address separation is a reality, all binary samples provided
 in the sdk can be used. I have had success spawning processes and one
 directx7 example will allow creation of an app and allow another to join it.
 Unfortunately, there isn't much for it to be able to do give the state of
 inter lobby messaging.

 A small issue will be the fact that DirectX 6.1(ie. DirectPlay4) introduces a layer of functionality
 inside the DP objects which provide guaranteed protocol delivery. This is
 even if the native protocol, IPX or modem for instance, doesn't guarantee it. I'm going to leave
 this kind of implementation to as close to the end as possible. However, I
 will implement an abstraction layer, where possible, for this functionality.
 It will do nothing to start, but will require only the implementation of the
 guaranteness to give final implementation.


 TODO:
   - (done) Header files for DP4 and DPL3
   - (done) Add stub functions for all DP4 and DPL3 interfaces
   - (done) Correct naming of the parameters for DP3 and DPL2
   - (done) Seperate out DP and DPL into multiple .c files
   - (done) Allow CoCreateInstance to create the new interfaces
   - (started)Implement mutual exclusion on object data for existing functions
   - (done) Create and move to correct dll directories (dplay and dplayx)
   - (done) Implement dplay in terms of dplayx
   - (done) Need a better internal implementation for the objects which scales and
     preferably doesn't involve casting structures. Solution is a crude ctor/dtor
     which can actually trap some runtime errors.
   - (done) More generic initialization and destruction helper methods based off
     the chosen internal implementation. Solution is a crude ctor/dtor.
   - Use only windows routines where an equivalent is available
   - (done) Fix wine dplay.h and dplobby.h header files to allow apps to create the ansi versions
   - (started) Port some WineLib test programs using sdk programs (both C and C++ progs)
   - (done) Implement a lib main for the dplayx dll (required for RunApplication, etc.)
   - (done)Figure out how to share the global memory correctly
   - Ensure that all dll stubs are present and the ordinals are correct
   - (started) Implementation of functionality
   - Addition of DirectX 7.0 functionality for direct play (try to catch that moving train)
   - bug fixes ;)
   - Implement some WineLib test programs using sdk programs as a skeleton
   - (done) Change all RegEnumKey calls to RegEnumKeyEx.
   - Change RegEnumKeyEx enumeration pattern to allow error handling and to
     share registry implementation (or at least simplify).
   - Add in appropriate RegCloseKey calls for all the opening we're doing...
   - Fix all the buffer sizes for registry calls. They're off by one - but in a safe direction.
   - Find out how to call the service provider dlls - they don't have a published interface!
   - Fix race condition on interface destruction
   - Handles need to be correctly reference counted
   - Need to check if we need to deallocate any list objects when destroying
     dplay interface
   - RunApplication process spawning needs to have correct syncronization.
   - Need to get inter lobby messages working.

 ENHANCEMENTS:
   - Improve footprint and realtime blocking by setting up a seperate data share
     between lobby application and client since there can be multiple apps per
     client.
   - Handle everything in UNICODE (as server does) and do conversions for ANSI
     interfaces. Should cut down on dplayx code base and maintanability (marginally)
     and could be used to improve efficiency of dialog with the server (it wouldn't
     have to do ANSI<->UNICODE transformations).


 Programs to make work:
   - lserver.exe (from sdk)
   - override.exe (from sdk)
   - dpchat.exe (from sdk)
   - duel.exe (from sdk)
   - dplaunch.exe (from sdk)

 Next API to implement on a per SDK program basis:
   override.exe
   - fixme:dplay:DirectPlayCreate Modem binding not supported yet
   - DirectPlay3AImpl_InitializeConnection
   - DirectPlay2AImpl_Open
   - ?

   dplaunch.exe
   - Just needs final process startup messages to be exchanged correctly!

   lserver.exe
   - IDirectPlayLobby2WImpl_Connect
   - fixme:dplay:DirectPlayCreate Modem binding not supported yet
   - IDirectPlay3WImpl_CreatePlayer
   - IDirectPlay3WImpl_CreateGroup
   - IDirectPlay3WImpl_SetGroupData
   - IDirectPlay3WImpl_Send
   - ?

   bellhop.exe
   - DP_SendSessionRequestBroadcast (implement the name server stuff)
   - ?

   dpslots.exe
   - IDirectPlayLobby3AImpl_ConnectEx
   - ?

   override.exe
   - DirectPlayCreate Service provider binding not supported yet
   - ?

 Other TODO:

 - look at problem with parsing the resource file for dplaunch. wrc problem?
 - I should be getting the dialog box to come up for dpchat when something is selected
 Call OLE32.7: CoCreateInstance(010017f0,00000000,00000001,010017e0,010094b4) ret=01002f38 fs=0237
 Call ADVAPI32.188: RegOpenKeyExA(80000002,5e08dd90 "Software\\Microsoft\\DirectPlay\\Compatibility",00000000,00020019,40e7f49c) ret=5e0b6e5a fs=0237


 Peter Hunnisett  -  hunnise@nortelnetworks.com
	This file contains information on the implementation of the direct play
	and direct play lobby features. There's lots to do and I'm not exactly
	implementing it overnight! Please lend a hand.

	Most methods and APIs are but stubs at this point. Examine the code
	to see what has been implemented. Use -debugmsg +dplay to get a
	reasonably thourough description of what's going on.

	Associated DirectX user header files are include/dplay.h, include/dplobby.h.

	Implementation of the DPLAY and DPLAYX dlls are both in the dlls/dplayx
	directory. Here's a brief description of the function of each of the files in that
	directory:

	dplay.c: Implementation of all the direct play object interfaces.

	dplobby.c: Implementation of all the direct play lobby interfaces.

	dpclassfactory.c: Implementation of the COM class factory which can create either
	direct play lobby or direct play lobby interfaces.

	dpinit.h: Header file so that dpclassfactory.c can access dplay and dplobby query
	functions. Shouldn't be included by anything else.

	dplayx_global.h,
	dplayx_global.c: Implementation of all things which are associated with dplay on
	the computer - ie shared resources and such. Methods in this
	compilation unit should not call anything out side this unit
	excepting base windows services and an interface to start the
	messaging thread.

	name_server.h,
	name_server.c: Implementation of all things which are associated with the name
	server functionality

	dplayx_main.c: LibMain executed for loading and unloading the dll. This will make
	the call to dplayx_global.c to request initialization and destruction
	of any global data.

	dplayx_queue.h: Linked list implementation for dplay/dplobby. Based off of the BSD
	version found in <sys/queue.h>

	dplayx_messages.h,
	dplayx_messages.c: Messaging interface required for both DirectPlay and
	DirectPlayLobby.

	Presently the architectural relationship between this files is a little shakey, but
	isn't so sufficiently bad that it needs fixing yet.

	I think I can safely say that any application which requires direct play
	or direct play lobby will not work at this point. Priority will be to get
	examples from the sdk running. Once they're at least partially working, I can
	get down to trying to get some of the games working.

	However, now that address separation is a reality, all binary samples provided
	in the sdk can be used. I have had success spawning processes and one
	directx7 example will allow creation of an app and allow another to join it.
	Unfortunately, there isn't much for it to be able to do give the state of
	inter lobby messaging.

	A small issue will be the fact that DirectX 6.1(ie. DirectPlay4) introduces a layer of functionality
	inside the DP objects which provide guaranteed protocol delivery. This is
	even if the native protocol, IPX or modem for instance, doesn't guarantee it. I'm going to leave
	this kind of implementation to as close to the end as possible. However, I
	will implement an abstraction layer, where possible, for this functionality.
	It will do nothing to start, but will require only the implementation of the
	guaranteness to give final implementation.


	TODO:
	- (done) Header files for DP4 and DPL3
	- (done) Add stub functions for all DP4 and DPL3 interfaces
	- (done) Correct naming of the parameters for DP3 and DPL2
	- (done) Seperate out DP and DPL into multiple .c files
	- (done) Allow CoCreateInstance to create the new interfaces
	- (started)Implement mutual exclusion on object data for existing functions
	- (done) Create and move to correct dll directories (dplay and dplayx)
	- (done) Implement dplay in terms of dplayx
	- (done) Need a better internal implementation for the objects which scales and
	preferably doesn't involve casting structures. Solution is a crude ctor/dtor
	which can actually trap some runtime errors.
	- (done) More generic initialization and destruction helper methods based off
	the chosen internal implementation. Solution is a crude ctor/dtor.
	- Use only windows routines where an equivalent is available
	- (done) Fix wine dplay.h and dplobby.h header files to allow apps to create the ansi versions
	- (started) Port some WineLib test programs using sdk programs (both C and C++ progs)
	- (done) Implement a lib main for the dplayx dll (required for RunApplication, etc.)
	- (done)Figure out how to share the global memory correctly
	- Ensure that all dll stubs are present and the ordinals are correct
	- (started) Implementation of functionality
	- Addition of DirectX 7.0 functionality for direct play (try to catch that moving train)
	- bug fixes ;)
	- Implement some WineLib test programs using sdk programs as a skeleton
	- (done) Change all RegEnumKey calls to RegEnumKeyEx.
	- Change RegEnumKeyEx enumeration pattern to allow error handling and to
	share registry implementation (or at least simplify).
	- Add in appropriate RegCloseKey calls for all the opening we're doing...
	- Fix all the buffer sizes for registry calls. They're off by one - but in a safe direction.
	- Find out how to call the service provider dlls - they don't have a published interface!
	- Fix race condition on interface destruction
	- Handles need to be correctly reference counted
	- Need to check if we need to deallocate any list objects when destroying
	dplay interface
	- RunApplication process spawning needs to have correct syncronization.
	- Need to get inter lobby messages working.

	ENHANCEMENTS:
	- Improve footprint and realtime blocking by setting up a seperate data share
	between lobby application and client since there can be multiple apps per
	client.
	- Handle everything in UNICODE (as server does) and do conversions for ANSI
	interfaces. Should cut down on dplayx code base and maintanability (marginally)
	and could be used to improve efficiency of dialog with the server (it wouldn't
	have to do ANSI<->UNICODE transformations).



	Programs to make work:
	- lserver.exe (from sdk)
	- override.exe (from sdk)
	- dpchat.exe (from sdk)
	- duel.exe (from sdk)
	- dplaunch.exe (from sdk)

	Next API to implement on a per SDK program basis:
	override.exe
	- fixme:dplay:DirectPlayCreate Modem binding not supported yet
	- DirectPlay3AImpl_InitializeConnection
	- DirectPlay2AImpl_Open
	- ?

	dplaunch.exe
	- Just needs final process startup messages to be exchanged correctly!

	lserver.exe
	- IDirectPlayLobby2WImpl_Connect
	- fixme:dplay:DirectPlayCreate Modem binding not supported yet
	- IDirectPlay3WImpl_CreatePlayer
	- IDirectPlay3WImpl_CreateGroup
	- IDirectPlay3WImpl_SetGroupData
	- IDirectPlay3WImpl_Send
	- ?

	bellhop.exe
	- DP_SendSessionRequestBroadcast (implement the name server stuff)
	- ?

	dpslots.exe
	- IDirectPlayLobby3AImpl_ConnectEx
	- ?

	override.exe
	- DirectPlayCreate Service provider binding not supported yet
	- ?

	Other TODO:

	- look at problem with parsing the resource file for dplaunch. wrc problem?
	- I should be getting the dialog box to come up for dpchat when something is selected
	Call OLE32.7: CoCreateInstance(010017f0,00000000,00000001,010017e0,010094b4) ret=01002f38 fs=0237
	Call ADVAPI32.188: RegOpenKeyExA(80000002,5e08dd90 "Software\\Microsoft\\DirectPlay\\Compatibility",00000000,00020019,40e7f49c) ret=5e0b6e5a fs=0237


	Peter Hunnisett - hunnise@nortelnetworks.com