home *** CD-ROM | disk | FTP | other *** search
/ Windows Game Programming for Dummies (2nd Edition) / WinGamProgFD.iso / pc / DirectX SDK / DXSDK / samples / Multimedia / DirectPlay / DataRelay / readme.txt < prev    next >
Encoding:
Text File  |  2001-10-10  |  6.6 KB  |  127 lines
  1. //-----------------------------------------------------------------------------
  2. // 
  3. // Sample Name: DataRelay Sample
  4. // 
  5. // Copyright (c) 1999-2001 Microsoft Corporation. All rights reserved.
  6. // 
  7. //-----------------------------------------------------------------------------
  8.  
  9.  
  10. Description
  11. ===========
  12.   The DataRelay is similar to SimplePeer but differs by sending a single 
  13.   target (or everyone) a packet of data with options specified in the 
  14.   dialog's UI. It uses a worker thread to process received data, and 
  15.   uses the ReturnBuffer() API so that no copying of the received buffers
  16.   is done.
  17.  
  18. Path
  19. ====
  20.   Source: DXSDK\Samples\Multimedia\DirectPlay\DataRelay 
  21.  
  22.   Executable: DXSDK\Samples\Multimedia\DirectPlay\Bin
  23.  
  24. User's Guide
  25. ============
  26.   Host or connect to a session in the same manner as explained in SimplePeer.
  27.   When the main dialog appears select the target, size, rate, and timeout values.
  28.   Then click "Push to Send". This will send a packet of data to the target as
  29.   the rate specified with the specified size.  Use the "Connection Info" dropdown 
  30.   to specify a target to gather connection info on periodically.
  31.  
  32. Programming Notes
  33. =================
  34.   The DataRelay sample is very similar in form to the SimplePeer sample.  For 
  35.   detailed programming notes on the basics this sample, refer to Programming 
  36.   Notes section of the SimplePeer sample.
  37.  
  38.   The DataRelay differs by sending a single target (or everyone) a packet of 
  39.   data with options specified in the dialog's UI. 
  40.  
  41.   When the "Push to Send" button is clicked, then win32 timer is created 
  42.   that goes off every number of ms according to the UI.
  43.  
  44.   * Upon the WM_TIMER labeled TIMERID_NETWORK, it calls SendNetworkData().
  45.     1. It creates a app defined struct, GAMEMSG_DATA_xxx on the heap.  
  46.        The struct derives from GAMEMSG_GENERIC.  GAMEMSG_GENERIC contains a 
  47.        packet type field so that the reciever and identify this app defined 
  48.        packet, and it contains a packet ID field.  This field is sequential 
  49.        and is displayed to the user whenever a packet is received.  The struct 
  50.        is created on the heap, since will use the DPNSEND_NOCOPY when calling 
  51.        SendTo() below.  The struct is filled with random data, however a real 
  52.        app would typically send player and world state data here.        
  53.     2. It then creates a GAMEMSG_DATA_NODE which is then handed off to the
  54.         app worker thread.  That thread will process the node, and
  55.        then update the UI to show that a packet was sent.  It is handed off
  56.        by adding the node to a linked list.  Since the worker thread also
  57.        accesses the linked list, we enter a critical section before adding the
  58.        node and leave it afterward.
  59.     3. A DPN_BUFFER_DESC is then filled out passing in a pointer to the 
  60.        app defined struct created above. 
  61.     4. IDirectPlay8Peer::SendTo is called passing in the DPN_BUFFER_DESC, thereby
  62.        sending the app defined struct, GAMEMSG_DATA_xxx.  We call SendTo with
  63.        the flags DPNSEND_NOLOOPBACK | DPNSEND_NOCOPY.  DPNSEND_NOLOOPBACK tells
  64.        DirectPlay to not to send the buffer to us, and DPNSEND_NOCOPY means that
  65.        DirectPlay should not copy the buffer.  When the DPNSEND_NOCOPY is used,
  66.        the app itself owns the buffer, and the buffer must be on the heap.
  67.        When the DPN_MSGID_SEND_COMPLETE comes in, we will delete the buffer.         
  68.     5. The event, g_hDPDataAvailEvent, is set telling the worker thread that 
  69.        there is data (a message to say that a packet was sent), is ready to 
  70.        be processed now.
  71.     
  72.   * Handle DirectPlay system messages.  See DirectPlayMessageHandler()
  73.         The DataRelay handles the typical messages as described in the 
  74.         SimplePeer programming notes, and in addition:
  75.         
  76.         - Upon DPN_MSGID_RECEIVE
  77.             1. It casts the pReceiveMsg->pReceiveData to a GAMEMSG_GENERIC*.
  78.             2. It then switches off the GAMEMSG_GENERIC's dwType. 
  79.             3. If its a GAME_MSGID_GAMEPACKET, then it creates and fills out
  80.                a GAMEMSG_DATA_NODE.  This node is then handed to a worker thread
  81.                so it can be processed outside of the DirectPlay message handler.
  82.                This is important since it keeps the DirectPlay threads working at
  83.                full speed.
  84.             4. After the node is added to the linked list using a critical section
  85.                to lock, it returns DPNSUCCESS_PENDING.  This is important since 
  86.                it tells DirectPlay that ownership of the buffer 
  87.                has been transferred to the application, and so DirectPlay will 
  88.                neither free nor modify it until ownership is returned 
  89.                to DirectPlay through the ReturnBuffer() call.
  90.  
  91.         - Upon DPN_MSGID_SEND_COMPLETE
  92.             1. It checks the pSendCompleteMsg->hResultCode for DPNERR_TIMEDOUT.
  93.             2. If this occurs then it creates a new GAMEMSG_DATA_NODE with dwType
  94.                set to DATA_TYPE_NETPACKET_TIMEOUT.  This will is passed to the 
  95.                worker thread.  The worker thread will process this node, and 
  96.                post a message to the dialog saying that the message timed out.
  97.                A realistic application would want to take the appropriate steps here,
  98.                such as resending new data or other measures.
  99.             3. It deletes the buffer from the heap since we specified, DPNSEND_NOCOPY,
  100.                so the buffer on the heap belows the app and it must clean it up. 
  101.          
  102.    * The worker thread.  See ProcessNetDataProc()
  103.         - Upon the g_hDPDataAvailEvent
  104.             1. When the event is signaled, then new data can be found in the 
  105.                linked list, g_DataHead.  So it calls ProcessData().
  106.             2. ProcessData() first enters the critical section, g_csDataList, so 
  107.                that the other threads don't modify the linked list while it is 
  108.                processing data.  It leaves this critical section at the end of the
  109.                loop.  Typically better locking mechanisms would be used so that the 
  110.                other threads (as well as the DirectPlay message handler threads) 
  111.                aren't blocked while data is processed on this thread.               
  112.             3. It runs through the linked list, processing each node.  For this
  113.                simple sample all it does is posting a message to the dialog thread,
  114.                containing a string for the dialog to display.
  115.             4. After it is done processing the node, it calls 
  116.                IDirectPlay8Peer::ReturnBuffer() so that DirectPlay can free
  117.                buffer that it passed us in DPN_MSGID_RECEIVE.
  118.              
  119.                
  120.             
  121.       
  122.        
  123.     
  124.     
  125.     
  126.  
  127.