次の方法で共有

IDirectPlay8Client::Connect メソッド

  • [アーティクル]

IDirectPlay8Client::Connect メソッド

サーバーへの接続を確立する。

構文

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

戻り値

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

DPNERR_HOSTREJECTEDCONNECTION 接続要求は拒否された。詳細については、DPN_MSGID_CONNECT_COMPLETE 型の ReplyData メンバを参照すること。
DPNERR_INVALIDAPPLICATION アプリケーションに指定されたグローバル一意識別子 (GUID) が無効である。
DPNERR_INVALIDDEVICEADDRESS ローカル コンピュータまたはアダプタのアドレスが無効である。
DPNERR_INVALIDFLAGS このメソッドに渡されたフラグは無効である。
DPNERR_INVALIDHOSTADDRESS 指定されたリモート アドレスが無効である。
DPNERR_INVALIDINSTANCE アプリケーションのインスタンスの GUID が無効である。
DPNERR_INVALIDINTERFACE インターフェイス パラメータが無効である。接続元プレーヤがクライアント/サーバー ゲームのクライアントまたはピアツーピア ゲームのピアではなかった場合、接続要求にこの値が返される。
DPNERR_INVALIDPASSWORD パスワードが必要なセッションに参加しようとしたときに、無効なパスワードが指定された。
DPNERR_NOCONNECTION 通信リンクが確立されなかった。
DPNERR_NOTHOST クライアントがホスト以外のコンピュータに接続しようとした。また、ホスト以外のコンピュータがアプリケーションの記述を設定しようとした場合に、このエラー値が返されることがある。
DPNERR_SESSIONFULL セッションに割り当てられているプレーヤの最大数に達したため、ホストまたはサーバーへの接続要求が失敗した。
DPNERR_ALREADYCONNECTED オブジェクトは既にセッションに接続されている。

注意

適切なホストとデバイスに関する情報がある場合、IDirectPlay8Client::Connect を呼び出す前にホストを列挙する必要はない。

IDirectPlay8Client::EnumHosts メソッドを呼び出し、Transmission Control Protocol/Internet Protocol (TCP/IP) サービス プロバイダを使うときにネットワーク アドレス変換 (NAT) とプロキシのサポートを向上させるか、モデム サービス プロバイダによるリダイヤルを避ける場合は、列挙をアクティブにして IDirectPlay8Client::Connect メソッドを呼び出すこと。列挙が完了するのを避けるには、dwEnumCount パラメータを INFINITE に設定し、接続処理が完了する前に列挙が終わらないようにするため IDirectPlay8Client::CancelAsyncOperation を使わない。また、DPNMSG_ENUM_HOSTS_RESPONSE メッセージの pAddressSender および pAddressDevice の各アドレス オブジェクトを変更せずに IDirectPlay8Client::Connect メソッドのパラメータ pHostAddr および pDeviceInfo に渡す。コールバック関数の外側でアドレス オブジェクトを IDirectPlay8Client::Connect に渡すには、IDirectPlay8Address::Duplicate または IDirectPlay8Address::AddRef を使ってオブジェクトの破棄を防ぎ、スレッドに依存しないコードを使ってポインタを保存する。接続が DPN_OK で完了するか、IDirectPlay8Client::Close が呼び出されると、DirectPlay は自動的に列挙を取り消す。

このメソッドを呼び出す前に、IDirectPlay8Client::EnumHosts を呼び出してアプリケーションの記述を取得できる。IDirectPlay8Client::EnumHosts を呼び出すと、見つかった各ホストの IDirectPlay8Address オブジェクトと DPN_APPLICATION_DESC 構造体と共に DPN_MSGID_ENUM_HOSTS_RESPONSE メッセージがメッセージ ハンドラに送信される。この情報は変更なしに IDirectPlay8Client::Connect メソッドに渡せる。

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

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

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

IDirectPlay8Client::Connect が同期して呼び出されると、次の結果が生じる。

  • 接続が成功する。アプリケーションは成功コードが入った DPN_MSGID_CONNECT_COMPLETE メッセージを受け取り、IDirectPlay8Client::Connect メソッドは DPN_OK を返す。
  • サーバーが接続を拒否したため、接続は失敗する。アプリケーションは DPNERR_HOSTREJECTEDCONNECTION 失敗コードが入った DPN_MSGID_CONNECT_COMPLETE メッセージを受け取る。IDirectPlay8Client::Connect メソッドもエラー コード DPNERR_HOSTREJECTEDCONNECTION を返す。DPN_MSGID_CONNECT_COMPLETE メッセージにより、クライアント アプリケーションはサーバーからの拒否の際に返されたデータを調べることができる。
  • 他の理由で接続は失敗する。アプリケーションは DPN_MSGID_CONNECT_COMPLETE メッセージを受け取らず、IDirectPlay8Client::Connect メソッドは該当するエラー コードを返す。

IDirectPlay8Client::Connect が非同期に呼び出されると、メソッドはすぐに DPNSUCCESS_PENDING を返す。接続が完了した後、接続の結果が入った DPN_MSGID_CONNECT_COMPLETE メッセージが続く。メソッドが DPNSUCCESS_PENDING を返さないのは、指定したパラメータの確認が失敗した場合だけである。その場合、該当するエラー コードを返す。

接続要求が完了すると、未処理の列挙はすべて取り消され、DPNERR_USERCANCEL が返される。

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

接続が完了すると、アプリケーションのメッセージ ハンドラに DPN_MSGID_CONNECT_COMPLETE メッセージが送信される。未処理の列挙はすべて取り消され、DPNERR_USERCANCEL が返される。

このメソッドで確立した接続を閉じるには、IDirectPlay8Client::Close メソッドを呼び出す。

「データ値の概要」では、各サービス プロバイダに必要なアドレス情報を指定している。

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