天行健 君子当自强而不息

本篇是使用DirectPlay进行网络互联（1）的续篇。
 

使用地址

一个网络使用IP地址和端口来传送数据，在DirectPlay中，使用DirectPlay专用对象IDirectPlay8Address来构造地址。

The IDirectPlay8Address interface contains generic addressing methods used to create and manipulate addresses for Microsoft® DirectPlay® . This interface is one of the interfaces available through the CLSID_DirectPlay8Address COM object.

The IDirectPlay8Address interface contains the following methods.

IDirectPlay8Address Methods	BuildFromURLW
	BuildFromURLA
	Duplicate
	SetEqual
	IsEqual
	Clear
	GetURLW
	GetURLA
	GetSP
	GetUserData
	SetSP
	SetUserData
	GetNumComponents
	GetComponentByName
	GetComponentByIndex
	AddComponent
	GetDevice
	SetDevice
	BuildFromDPADDRESS

 

Remarks

In order to deliver messages, each participant in a multiplayer game must have a unique address. Addresses can refer either to the computer that your application is running on (device address), or a computer that your application needs to communicate with (host address).

DirectPlay represents addresses as URLs. These URLs are then encapsulated in the address object so that they can be passed to or from the DirectPlay API. In general, address URLs are strings that consist of three basic components in the following order: scheme, scheme separator, and data string.

All DirectPlay addresses use "x-directplay" as the scheme, and ":/" as the scheme separator. Using ":/" as a separator implies that the data that follows is opaque. In other words, the data string does not conform to any Internet standard, and should simply be passed on to the receiving application without modification. All DirectPlay URLs thus have the following general form:

x-directplay:/[data string]

There are two basic approaches to handling address objects:

• Handle the data string directly, using normal string manipulation techniques.
• Use the methods exposed by IDirectPlay8Address to obtain or modify the individual elements of the data string.

For more information on DirectPlay addresses, see DirectPlay Addressing.

常用的 IDirectPlay8Address方法有三个：

IDirectPlay8Address::Clear	清除所有地址数据
IDirectPlay8Address::SetSP	设置服务提供者
IDirectPlay8Address::AddComponent	添加地址组件

使用地址对象之前，需要使用CoCreateInstance函数来创建它：
 

添加组件

一个地址对象只是包含Unicode文本字符串的简单对象，该文本字符串包含服务提供者、端口号以及其他可选信息，下图显示了可以添加到地址对象的组件以及每个组件的数据类型：

AddComponent函数的惟一用途就是创建该字符串以供其他对象使用。

Adds a component to the address. If the component is part of the address, it is replaced by the new value in this call.

Values are specified in native formats when making this call. Therefore, the lpvData parameter should be a recast pointer to a variable that holds the data in the native format. For example, if the component is a GUID, the lpvData parameter should be a recast pointer to a GUID.

This method validates that the predefined component types are the right format.

HRESULT AddComponent(
const WCHAR *const pwszName,
const void *const lpvData,
const DWORD dwDataSize,
const DWORD dwDataType 
);

Parameters

pwszName

[in] NULL-terminated Unicode string that contains the key for the component.

lpvData

[in] Pointer to a buffer that contains the value associated with the specified key. Data should be specified in its native format.

dwDataSize

[in] Size, in bytes, of the data in the buffer located at lpvData. The size depends on the data type. If the size is not specified correctly, the method returns DPNERR_INVALIDPARAM.

DWORD

Size = sizeof( DWORD )

GUID

Size = sizeof( GUID )

String

Size = size of the string in bytes, including NULL terminator.

dwDataType

[in] Data type of the value associated with this key. The data type can be one of the following:

DPNA_DATATYPE_STRING

Data is a NULL-terminated string.

DPNA_DATATYPE_DWORD

Data is a DWORD.

DPNA_DATATYPE_GUID

Data is a GUID.

DPNA_DATATYPE_BINARY

Data is in raw binary format.

Return Values

Returns S_OK if successful, or one of the following error values.

DPNERR_INVALIDPARAM

DPNERR_INVALIDPOINTER

DPNERR_NOTALLOWED

Remarks

See DirectPlay Addressing for a discussion of various address components and their keys.

设置服务提供者

下一步要做的就是选择服务提供者，调用 IDirectPlay8Address::SetSP函数来设置。

Sets the service provider GUID in the address object. If a service provider is specified for this address, it is overwritten by this call.

HRESULT SetSP(
const GUID *const pguidSP
);

Parameters

pguidSP

[in] Pointer to the service provider GUID.

Return Values

Returns S_OK if successful, or one of the following error values.

DPNERR_INVALIDPOINTER

DPNERR_NOTALLOWED

 

选择端口

无论是主持一次会话（作为服务器端或单点）还是使用客户端网络模型连接到一个远程系统，接下来必须要做的就是选择端口，如果要连接到远程系统，就必须知道应用程序所使用的端口，以便能够连接到远程系统以及发送数据到远程系统。端口号可以随意选择，但是不要使用保留端口号（1 - 1024），选择1024以上的端口号会比较安全。可以通过指定端口号0而让DirectPlay来选择一个端口号，但是这样做的弊病在于端口号可能为任意数字，就需要对端口号进行查询，推荐的做法是自己选择一个端口号。

设置端口号使用 IDirectPlay8Address::AddComponent函数。

 

使用消息处理函数

消息处理回调函数非常简单，它仅仅需要区分接收到的是哪一种消息，并尽可能快地处理消息，可以将消息处理函数想象成一个漏斗，如下图所示:

以下是一个简单的消息处理函数代码实例：

通过switch-case语句，可以快速找到要处理的消息，而略过其他消息。如果处理消息成功，就返回S_OK，否则返回E_FAIL表示处理失败。每个消息都带有一个数据缓冲区，这些缓冲区被类型转换为适当的结构体，除了它们是以DPNMSG_而不是DPN_MSGID_开头之外，这些结构体和消息宏几乎具有相同的命名规则。
 

配置会话信息

每一个网络对象都需要知道一些要主持或要加入的会话信息，这些信息包含在一个结构体中：

Describes the settings for a Microsoft® DirectPlay® application.

typedef struct _DPN_APPLICATION_DESC{
 DWORD dwSize;
 DWORD dwFlags;
 GUID guidInstance;
 GUID guidApplication;
 DWORD dwMaxPlayers;
 DWORD dwCurrentPlayers;
 WCHAR* pwszSessionName;
 WCHAR* pwszPassword;
 PVOID pvReservedData;
 DWORD dwReservedDataSize;
 PVOID pvApplicationReservedData;
 DWORD dwApplicationReservedDataSize;
} DPN_APPLICATION_DESC, *PDPN_APPLICATION_DESC;

Members

dwSize

Size of the DPN_APPLICATION_DESC structure. The application must set this member before it uses the structure.

dwFlags

One of the following flags describing application behavior.

DPNSESSION_CLIENT_SERVER

This type of session is client/server. This flag cannot be combined with DPNSESSION_MIGRATE_HOST.

DPNSESSION_MIGRATE_HOST

Used in peer-to-peer sessions, enables host migration. This flag cannot be combined with DPNSESSION_CLIENT_SERVER.

DPNSESSION_NODPNSVR

Do not forward enumerations to your host from DPNSVR. See Using the DirectPlay DPNSVR Application for details.

DPNSESSION_REQUIREPASSWORD

The session is password protected. If this flag is set, pwszPassword must be a valid string.

guidInstance

Globally unique identifier (GUID) that is generated by DirectPlay at startup, representing the instance of this application. This member is an [out] parameter when calling the GetApplicationDesc method exposed by the IDirectPlay8Peer, IDirectPlay8Client, and IDirectPlay8Server interfaces. It is an optional [in] parameter when calling the Connect method exposed by the IDirectPlay8Peer and IDirectPlay8Client interfaces. It must be set to GUID NULL when you call the SetApplicationDesc method exposed by the IDirectPlay8Server and IDirectPlay8Peer interfaces. You cannot obtain this GUID by calling the IDirectPlay8Server::Host or IDirectPlay8Peer::Host methods. You must obtain the GUID by calling a GetApplicationDesc method.

guidApplication

Application GUID.

dwMaxPlayers

Variable of type DWORD, specifying the maximum number of players allowed in the session. Set this member to 0 to specify an unlimited number of players.

dwCurrentPlayers

Variable of type DWORD specifying the number of players currently connected to the session. This member is an [out] parameter that is set only by the GetApplicationDescription method exposed by IDirectPlay8Peer, IDirectPlay8Client, and IDirectPlay8Server.

pwszSessionName

Pointer to a variable of type WCHAR specifying the Unicode name of the session. This member is set by the host or server only for informational purposes. A client cannot use this name to connect to a host or server.

pwszPassword

Pointer to a variable of type WCHAR specifying the Unicode password that is required to connect to the session. This must be NULL if the DPNSESSION_REQUIREPASSWORD is not set in the dwFlags member.

pvReservedData

Pointer to DirectPlay reserved data. An application should never modify this value.

dwReservedDataSize

Variable of type DWORD specifying the size of data contained in the pvReservedData member. An application should never modify this value.

pvApplicationReservedData

Pointer to application-specific reserved data. This value is optional and may be set to NULL.

dwApplicationReservedDataSize

Variable of type DWORD specifying the size of the data in the pvApplicationReservedData member. This value is optional and may be set to 0.

Remarks

Multiple instances of the application can run simultaneously. "Application" refers to a specific instance of an application.

The dwMaxPlayers, pvApplicationReservedData, dwApplicationReservedDataSize, pwszPassword, and pwszSessionName members can be set when calling the Host or SetApplicationDesc methods exposed by the IDirectPlay8Server and IDirectPlay8Peer interfaces.

When connecting to a password protected session, the data in the pwszPassword member is transmitted in clear text to the host.

会话数据

一个服务器端需要配置允许的最大玩家数（如果需要进行限制）、会话名称和登陆密码、会话标志以及应用程序GUID，如果不想限制最大玩家数，将dwMaxPlayers字段设置为0即可。
 
客户端结构体所需设置的信息包括要加入的会话名称和密码、客户端 / 服务器端会话标志以及应用程序GUID。一定要使用和服务器端相同的应用程序GUID，这样客户端和服务器端才能在网络中找到对方。

服务器端的处理

获得网络的第一步是创建一个服务器端。服务器端扮演了网络游戏的中央处理单元，所有玩家通过客户端应用程序连接到服务器端并在二者之间来回传输数据。服务器端保持游戏数据同步并告知玩家当前的游戏状态，虽然对于小型网络游戏而言，这并不是最快的办法，但对于大型网络游戏而言，则是最好的方法。

要创建服务器端，需要调用IDirectPlay8Server::Host来主持会话。

Creates a new client/server session, hosted by the local computer.

HRESULT Host(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address **const prgpDeviceInfo,
const DWORD cDeviceInfo,
const DPN_SECURITY_DESC *const pdpSecurity,
const DPN_SECURITY_CREDENTIALS *const pdpCredentials,
VOID *const pvPlayerContext,
const DWORD dwFlags
);

Parameters

pdnAppDesc

[in] Pointer to a DPN_APPLICATION_DESC structure that describes the application.

prgpDeviceInfo

[in] Pointer to an array of IDirectPlay8Address objects containing device addresses that should be used to host the application.

cDeviceInfo

[in] Variable of type DWORD that specifies the number of device address objects in the array pointed to by prgpDeviceInfo.

pdpSecurity

[in] Reserved. Must be set to NULL.

pdpCredentials

[in] Reserved. Must be set to NULL.

pvPlayerContext

[in] Pointer to the context value of the player. This value is preset when the local computer handles the DPN_MSGID_CREATE_PLAYER message. This parameter is optional, and may be set to NULL.

dwFlags

[in] The following flag can be specified.

DPNHOST_OKTOQUERYFORADDRESSING

Setting this flag will display a standard Microsoft® DirectPlay® dialog box, which queries the user for more information if not enough information is passed in this method.

Return Values

Returns S_OK if successful, or the following error value.

DPNERR_DATATOOLARGE

DPNERR_INVALIDPARAM

Remarks

If you set the DPNHOST_OKTOQUERYFORADDRESSING flag in dwFlags, the service provider may attempt to display a dialog box to ask the user to complete the address information. You must have a visible window present when the service provider tries to display the dialog box, or your application will lock.

The maximum size of the application data that you assign to the pvApplicationReservedData member of the DPN_APPLICATION_DESC structure is limited by the service provider's Maximum Transmission Unit. If your application data is too large, the method will fail and return DPNERR_DATATOOLARGE.

以下是创建服务器端会话的代码示例：
 
处理玩家

服务器端创建好之后，接收到的第一个消息就是创建一个玩家。创建的第一个玩家总是主机玩家，然后其他玩家才开始被创建和释放，但是在整个会话过程中，主机玩家始终都存在。创建玩家消息通过DPN_MSGID_CREATE_PLAYER定义，并且消息缓冲区被类型转换成 DPNMSG_CREATE_PLAYER结构体。

Microsoft® DirectPlay® generates the DPN_MSGID_CREATE_PLAYER message when a player is added to a peer-to-peer or client/server session.

The DPNMSG_CREATE_PLAYER structure contains information for the DPN_MSGID_CREATE_PLAYER system message.

typedef struct _DPNMSG_CREATE_PLAYER{
    DWORD  dwSize;
    DPNID  dpnidPlayer;
    PVOID  pvPlayerContext;
} DPNMSG_CREATE_PLAYER, *PDPNMSG_CREATE_PLAYER;

dwSize

Size of this structure.

dpnidPlayer

DPNID of the player that was added to the session.

pvPlayerContext

Player context value.

Return Values

Return DPN_OK.

Remarks

The only method of setting the player context value is through this system message. You can either set the player context value directly, through this message, or indirectly through DPN_MSGID_INDICATE_CONNECT. Once a player context value has been set, it cannot be changed.

玩家相关数据指针pvPlayerContext是用来在应用程序中定义玩家的信息，该数据指针可以指向一个结构体、类实例或包含了玩家名称、健康状态、年龄、当前武器以及护甲等的数据缓冲区。通过把玩家相关数据指针传递给DirectPlay，它就能带来更快的访问速度。因为时间关系，必须很快遍历一个已登录玩家的列表来查找一个匹配的玩家ID时，这样做就能节省时间。

一个玩家有一个与之关联的名称，而且要能够取回玩家名称以便在游戏中使用（因为没有人想使用一个数字作为其名称），这就是IDirectPlay8Server:: GetClientInfo函数所实现的功能。

Retrieves the client information set for the specified client.

HRESULT GetClientInfo(
const DPNID dpnid,
DPN_PLAYER_INFO *const pdpnPlayerInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

Parameters

dpnid

[in] Variable of type DPNID that specifies the identifier of the client to retrieve the information for.

pdpnPlayerInfo

[out] Pointer to a DPN_PLAYER_INFO structure that is filled with client information. If pdwSize is not set to NULL, you must set pdpnPlayerInfo.dwSize to an appropriate value.

pdwSize

[in,out] Pointer to a variable of type DWORD that contains the size of the client data, in bytes, returned in the pdpnPlayerInfo parameter. If the buffer is too small, this method returns DPNERR_BUFFERTOOSMALL and this parameter contains the size of the required buffer.

dwFlags

[in] Flags describing the information returned for the client. Currently, both of the following flags are returned.

DPNINFO_NAME

The DPN_PLAYER_INFO structure contains the name set for the client.

DPNINFO_DATA

The DPN_PLAYER_INFO structure contains the data set for the client.

Return Values

Returns S_OK if successful, or one of the following error values.

DPNERR_BUFFERTOOSMALL

DPNERR_INVALIDPARAM

DPNERR_INVALIDPLAYER

Remarks

Call this method after the server receives a DPN_MSGID_CLIENT_INFO message from the application. This message indicates that a client has updated its information.

Microsoft® DirectPlay® returns the DPN_PLAYER_INFO structure, and the pointers assigned to the structure's pwszName and pvData members in a contiguous buffer. If the two pointers were set, you must have allocated enough memory for the structure, plus the two pointers. The most robust way to use this method is to first call it with pdwSize set to NULL. When the method returns, pdwSize will point to the correct value. Use that value to allocate memory for the structure and call the method a second time to retrieve the information.

When the method returns, the dwInfoFlags member of the DPN_PLAYER_INFO structure will always have the DPNINFO_DATA and DPNINFO_NAME flags set, even if the corresponding pointers are set to NULL. These flags are used when calling IDirectPlay8Client::SetClientInfo, to notify DirectPlay of which values have changed.

Transmission of nonstatic information should be handled with the IDirectPlay8Client::Send method because of the high cost of using the IDirectPlay8Client::SetPeerInfo method.

The player sets the information by calling IDirectPlay8Client::SetClientInfo.

pdpnPlayerInfo指向玩家信息结构体：

Describes static player information.

typedef struct _DPN_PLAYER_INFO{
    DWORD  dwSize;
    DWORD  dwInfoFlags;
    PWSTR  pwszName;
    PVOID  pvData;
    DWORD  dwDataSize;
    DWORD  dwPlayerFlags;
} DPN_PLAYER_INFO, *PDPN_PLAYER_INFO;

Members

dwSize

Variable of type DWORD describing the size of this structure.

dwInfoFlags

Variable of type DWORD containing flags that specify the type of information contained in this structure. When a GetPlayerInfo method returns, the dwInfoFlags member of the DPN_PLAYER_INFO will always have both flags set, even if the corresponding pointers are set to NULL. These flags are used when calling IDirectPlay8Peer::SetPeerInfo, to notify Microsoft® DirectPlay® which values have changed.

DPNINFO_NAME

The pwszName member contains valid data.

DPNINFO_DATA

The pvData member contains valid data.

pwszName

Pointer to a variable of type PWSTR specifying the Unicode name of the player.

pvData

Pointer to the data describing the player.

dwDataSize

Variable of type DWORD that specifies the size of the data contained in the pvData member.

dwPlayerFlags

Variable of type DWORD that may contain one of the following flags.

DPNPLAYER_LOCAL

This information is for the local player.

DPNPLAYER_HOST

This player is the host for the application.

Remarks

When using this structure in the IDirectPlay8Peer::GetPeerInfo and IDirectPlay8Server::GetClientInfo methods, dwInfoFlags must be set to 0.

When using this structure in the IDirectPlay8Client::SetClientInfo, IDirectPlay8Peer::SetPeerInfo, or IDirectPlay8Server::SetServerInfo methods, dwPlayerFlags should be set to zero.

 

以下是处理创建玩家的代码实例：