//-----------------------------------------------------------------------------
//
// Sample Name: ChatPeer Sample
//
// Copyright (c) 1999-2001 Microsoft Corporation. All rights reserved.
//
//-----------------------------------------------------------------------------
Description
===========
ChatPeer is similar in form to SimplePeer. Once a player hosts or connects
to a session, the players can chat with either other by passing text
strings.
Path
====
Source: DXSDK\Samples\Multimedia\DirectPlay\ChatPeer
Executable: DXSDK\Samples\Multimedia\DirectPlay\Bin
User's Guide
============
Refer to User's Guide section of the SimplePeer sample.
Programming Notes
=================
The ChatPeer sample is very similar in form to the SimplePeer sample. For
detailed programming notes on the basics this sample, refer to Programming
Notes section of the SimplePeer sample.
The ChatPeer differs by letting clients send text strings to all players
connected to the session.
* The "Send" button is pressed. See SendChatMessage().
1. Retrieves the text string from the dialog.
2. Fills a app defined struct, GAMEMSG_CHAT. This struct has
a message type ID as the first BYTE. This lets our app
figure out what type of app message they received, however
ChatPeer only uses one app defined message. See StagedPeer
for a more complex example of this process.
3. Fills out a DPN_BUFFER_DESC struct using the GAMEMSG_CHAT buffer.
4. Calls IDirectPlay8Peer::SendTo() with the DPN_BUFFER_DESC. It passes
DPNID_ALL_PLAYERS_GROUP so this message goes to everyone.
* Handle DirectPlay system messages. See DirectPlayMessageHandler()
The ChatPeer handles the typical messages as described in the
SimplePeer programming notes, and in addition:
- Upon DPN_MSGID_RECEIVE message:
1. It casts pReceiveMsg->pReceiveData into a generic app defined
structure, GAMEMSG_GENERIC. This helps to figure out what structure
is really contained in pReceiveMsg->pReceiveData. For this simple
example, if the ID is GAME_MSGID_CHAT it casts the buffer to a
GAMEMSG_CHAT*.
2. It then creates a new APP_QUEUED_DATA struct which contains a pointer
to the GAMEMSG_CHAT buffer, and the a DirectPlay handle linked to the
GAMEMSG_CHAT buffer.
3. We then post a user defined message, WM_APP_CHAT, to the dialog thread
with the lParam equal to a pointer to the APP_QUEUED_DATA struct and
the wParam equal to the DPNID of the player who sent us the buffer.
We post a message since this lets us return from the DirectPlay message
handler quickly. In a complex game if the handler threads take too
long its possible that a backlog of network data may arise.
4. We return from DirectPlayMessageHandler() with the result code
of DPNSUCCESS_PENDING. This error code tells DirectPlay that the buffer
we got in the DPN_MSGID_RECEIVE message is still in use by our app.
This allows us to not to have to copy the buffer, but instead pass a
pointer of it off to a worker thread. This simple sample just uses
the main dialog thread to process queued data. For a more complex
example of this process see the DataRelay sample.
* Upon receiving WM_APP_CHAT in the message loop
This is posted to the message loop by one DirectPlay message handler threads
whenever we receive a chat message. See above for more detail. Here's what
happens:
1. Cast the wParam to a DPNID. This is the player that sent the message.
2. Calls IDirectPlay8Peer::GetPlayerContext(). This retrieves a user
specified pointer (which we cast to a APP_PLAYER_INFO*) associated with
this player. See the SimplePeer programming notes for more info on how
this is setup. Also, note that since player can be deleted at any time,
we need to use ref counting to make sure this player context struct isn't
deleted while we are still using it.
3. Cast the lParam into a APP_QUEUED_DATA*. This tells us the buffer, and the DirectPlay
handle associated with that buffer.
4. Process the buffer by adding it's text string to the dialog.
5. Release the APP_PLAYER_INFO* since we are done using it.
6. Now DirectPlay can free the receive buffer since we are done with it.
So return the buffer to DirectPlay by calling IDirectPlay8Peer::ReturnBuffer,
passing in the DirectPlay buffer handle.
7. Deletes the APP_QUEUED_DATA from the heap
LGram16
e067522598