Microsoft DirectX 8.0 (C++)

IDirectPlay8Client::Connect

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

このメソッドを呼び出す前に、IDirectPlay8Client::EnumHosts を呼び出してアプリケーションの記述を取得することができる。EnumHosts メソッドは、ホストされているアプリケーションごとに DPN_APPLICATION_DESC 構造体を返す。この構造体は、アプリケーションの GUID を含め、アプリケーションを記述する。

このメソッドが非同期に呼び出される場合 (デフォルト)、接続が完了すると、アプリケーションのメッセージ ハンドラに 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 pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

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

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。要求が非同期で処理される場合、メソッドが直ちに処理されると、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
DPNERR_ALREADYCONNECTED

注意

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

このメソッドが呼び出されると、サーバーのメッセージ ハンドラに DPN_MSGID_INDICATE_CONNECT メッセージが送信される。このメッセージの取得時、ホストは接続応答データを Connect メソッドに渡すことがある。接続応答データは、ホストが接続を承認しないことを示すメッセージを送信することがある。その後呼び出し元アプリケーションは、この応答を適切に処理することができる。

Connect() が成功した場合、完了時の hResultCode は S_OK を示す。それ以外の場合は、エラーを示す。Host プレーヤーが DPN_MSGID_INDICATE_CONNECT メッセージから S_OK 以外を返した場合、完了のエラー コードは DPNERR_HOSTREJECTEDCONNECTION であることが多い。

接続が完了すると、アプリケーションのメッセージ ハンドラに DPN_MSGID_CONNECT_COMPLETE メッセージが送信される。

このメソッドで確立した接続を閉じるには、IDirectPlay8Client::Close メソッドを呼び出す。Connect() への呼び出しが成功した後、すべての残っている列挙は DPNERR_USERCANCEL を返してキャンセルされる。

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

動作環境

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