Microsoft DirectX 8.0 (C++)

IDirectPlay8Peer::Connect

ピアツーピア セッションで、すべてのピアへの接続を確立する。一度接続が確立すると、インターフェイス上の通信チャネルが開き、アプリケーションはメッセージの到着を待機する。接続が完了するまで、IDirectPlay8Peer::SendTo メソッドを使用してメッセージを送信できない。

このメソッドを呼び出す前に、IDirectPlay8Peer::EnumHosts を呼び出して、関連付けられているホストのアプリケーション記述とアドレスを取得できる。EnumHosts メソッドは、現在ホストされているアプリケーションごとに DPN_APPLICATION_DESC 構造体を返す。この構造体は、アプリケーションのインスタンス GUID を含め、アプリケーションを記述する。

このメソッドが非同期に呼び出され (デフォルト)、DPNSUCCESS_PENDING を返した場合、接続が完了すると、アプリケーションのメッセージ ハンドラに DPN_MSGID_CONNECT_COMPLETE メッセージが送信される。

HRESULT Connect(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address *const pHostAddr,
IDirectPlay8Address *const pDeviceInfo,
const DPN_SECURITY_DESC *const pdnSecurity,
const DPN_SECURITY_CREDENTIALS *const pdnCredentials,
const void *const pvUserConnectData,
const DWORD dwUserConnectDataSize,
void *const pvPlayerContext,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

pdnAppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 構造体へのポインタ。このメソッドで使用されるのは、この構造体の一部のメンバのみである。設定しなければならないメンバは、dwSize および guidApplication のみである。guidInstancepwszPassword、および dwFlags も設定できる。
pHostAddr
IDirectPlay8Address へのポインタ。このインターフェイスは、ホストするコンピュータへの接続に使用されるアドレス情報を指定する。
pDeviceInfo
IDirectPlay8Address インターフェイスへのポインタ。このポインタは、サーバーへの接続に使用するネットワーク アダプタ (NIC、モデムなど) を指定する。
pdnSecurity
予約済み。NULL に設定しておく。
pdnCredentials
予約済み。NULL に設定しておく。
pvUserConnectData
接続を詳しく確認するためにホストまたはサーバーに提供されるアプリケーション固有のデータへのポインタ。このデータは、pvUserConnectData メンバの DPN_MSGID_INDICATE_CONNECT メッセージに送信される。このパラメータはオプションであり、ユーザー コードによる余分な接続の確認が提供されない場合は、NULL に設定することができる。
dwUserConnectDataSize
pvUserConnectData パラメータに含まれるデータのサイズを指定する DWORD 型の変数。
pvPlayerContext
ローカル プレーヤーのコンテキスト値へのポインタ。この値は、ローカル コンピュータが DPN_MSGID_CREATE_PLAYER メッセージを処理するときに事前に設定される。このパラメータはオプションであり、NULL に設定できる。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_CONNECT_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
DPNHANDLE。メソッドが値を返すと、phAsyncHandle は、IDirectPlay8Peer::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNCONNECT_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
接続モードを記述するフラグ。次のフラグを設定できる。
DPNCONNECT_OKTOQUERYFORADDRESSING
このフラグを設定すると、Microsoft® DirectPlay® の標準のダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細について問い合わされる。
DPNCONNECT_SYNC
接続要求を同期をとりながら処理する。その場合も、メッセージ ハンドラは DPN_MSGID_CONNECT_COMPLETE メッセージを受け取り、ホストからの接続応答を処理できる。このメッセージは、IDirectPlay8Peer::Connect が値を返すまでに受け取る。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合は、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_HOSTREJECTEDCONNECTION
DPNERR_INVALIDAPPLICATION
DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDINSTANCE
DPNERR_INVALIDINTERFACE
DPNERR_INVALIDPASSWORD
DPNERR_NOCONNECTION
DPNERR_NOTHOST
DPNERR_SESSIONFULL

注意

複数の列挙を同時に実行し、1 つの接続中に実行できるが、インターフェイスごとに 1 つの接続しか利用できない。1 つ以上のアプリケーションへの接続を確立するには、別のインターフェイスを作成しなければならない。

このメソッドが非同期に呼び出された場合 (デフォルト)、接続が完了すると、アプリケーションのメッセージ ハンドラに DPN_MSGID_CONNECT_COMPLETE メッセージが送信される。このメソッドがエラーを返した場合、完了メッセージは送信されない。

このメソッドが呼び出されると、ホストのメッセージ ハンドラに DPN_MSGID_INDICATE_CONNECT メッセージが送信される。ホストがこのメッセージを処理するときは、プレーヤーが受け取る接続応答データを DPN_MSGID_CONNECT_COMPLETE メッセージで指定することができる。ホストが接続を受け入れた場合、接続応答データにはカスタム スタートアップ情報が入っている場合がある。接続が拒否された場合、接続応答データに拒否の説明が入っている場合がある。

IDirectPlay8Peer::Close を呼び出してホストとの接続を終了する必要がある。Connect() への呼び出しが成功した後、すべての残っている列挙は DPNERR_USERCANCEL を返してキャンセルされる。

  dwFlags に DPNCONNECT_OKTOQUERYFORADDRESSING フラグを設定した場合、サービス プロバイダは、ダイアログ ボックスを表示して、ユーザーにアドレス情報の入力を求めようとする。サービス プロバイダがダイアログボックスの表示を試みるときには、表示可能なウィンドウが存在している必要がある。ウィンドウがない場合、アプリケーションはロックする。

動作環境

  Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
  Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
  ヘッダー : Dplay8.h で宣言。