次の方法で共有

IDirectPlay8Peer::Connect メソッド

  • [アーティクル]

IDirectPlay8Peer::Connect メソッド

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

構文

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
    [in] アプリケーションを記述する DPN_APPLICATION_DESC 構造体へのポインタ。このメソッドで使われるのは、この構造体の一部のメンバのみである。設定しなければならないメンバは、dwSize および guidApplication のみである。guidInstance、pwszPassword、および dwFlags も設定できる。
  • 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 型の変数。
  • pvPlayerContext
    [in] ローカル プレーヤのコンテキスト値へのポインタ。この値は、ローカル コンピュータが DPN_MSGID_CREATE_PLAYER メッセージを処理するときに事前に設定される。このパラメータはオプションであり、NULL に設定できる。
  • pvAsyncContext
    [in] ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_CONNECT_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
  • phAsyncHandle
    [out] DPNHANDLE。メソッドが値を返すと、phAsyncHandle は、IDirectPlay8Peer::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNCONNECT_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
  • dwFlags
    [in] 接続モードを記述するフラグ。次のフラグを設定できる。
    • DPNCONNECT_OKTOQUERYFORADDRESSING
      このフラグを設定すると、DirectPlay の標準ダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細についてユーザーに問い合わせる。
    • DPNCONNECT_SYNC
      接続要求を同期をとりながら処理する。その場合も、メッセージ ハンドラは DPN_MSGID_CONNECT_COMPLETE メッセージを受け取り、ホストからの接続応答を処理できる。このメッセージは、IDirectPlay8Peer::Connect が値を返すまでに受け取る。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は 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 セッションに割り当てられているプレーヤの最大数に達したため、ホストまたはサーバーへの接続要求が失敗した。

注意

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

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

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

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

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

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 が返される。

IDirectPlay8Peer::Close を呼び出してホストとの接続を終了する必要がある。

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

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