Platform SDK: DirectX

IDirectPlay4::CreateGroup

IDirectPlay4::CreateGroup メソッドは、カレント セッション内でグループを作成する。グループとは、プレーヤーまたはその他のグループの論理的な集合である。

HRESULT CreateGroup(
  LPDPID lpidGroup,
  LPDPNAME lpGroupName,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

パラメータ

lpidGroup
DirectPlay グループ ID が設定される変数へのポインタ。この値は、DirectPlay により定義される。
lpGroupName
グループの名前が設定されている DPNAME 構造体へのポインタ。NULL が設定されている場合は、グループに初期設定名がないことを示す。lpGroupName の名前はユーザーが使用するためだけに設定する。システム内では使用されないので、一意でなくてもかまわない。
lpData
システム内でグループ ID に関連付けるアプリケーションにより定義されたリモート データのブロックへのポインタ。NULL が設定されている場合は、グループに初期設定名がないことを示す。ここで指定したデータは、IDirectPlay4::SetGroupData が呼び出された場合と同じように、セッション内のその他すべてのアプリケーションに伝播されるリモート データであると見なされる。
dwDataSize
lpData が示すデータ ブロックのサイズ (バイト単位)。
dwFlags
作成するグループのタイプを示すフラグ。デフォルト (dwFlags = 0) では、グループの所有権は所有者がセッションを離れた時点でホストに移行し、グループは明示的に破棄されるまで存続する。

設定可能な値は、次のいずれかである。

DPGROUP_HIDDEN
隠しフラグによりグループを作成する。グループが列挙されると、隠しフラグが設定される。ロビー セッションでは、隠しグループは IDirectPlay4::AddGroupToGroup により作成されたショートカットからのみ使用できる。このフラグは、プレーヤーにとって DPPLAYER_SPECTATOR フラグと同じように機能する。
DPGROUP_STAGINGAREA
グループをステージング領域として作成する。ステージング領域は、新しいセッションを起動するためにプレーヤーを整列するときに使用する。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

注意

グループがクライアント/サーバー セッションで作成された場合、グループ通知メッセージは送信されない。グループは、マシンがクライアントであるかホストであるかに関係なく、そのグループを作成したマシンでしか表示できない。

グループがピアツーピア セッションで作成された場合、CreateGroup によりその他のすべてのプレーヤーに送信される DPMSG_CREATEPLAYERORGROUP システム メッセージが生成される。アプリケーションで IDirectPlay4::Send を使用すると、1 つのメッセージをグループ ID に送信するだけでそのグループ内のすべてのプレーヤーにメッセージを送信できる。DirectPlay は、マルチキャストを使用して、このメッセージを送信する (この機能がサービス プロバイダによりサポートされている場合) か、または各メッセージをグループ内の各プレーヤーに送信する。

メッセージの受け渡しやデータの関連付けでグループを識別するときは、アプリケーションに返されるグループ ID を使用する。DirectPlay により割り当てられたプレーヤー ID やグループ ID はセッション内で常に一意である。

CreateGroup により作成されるグループは、セッション内で最上位グループとなる。これらは、IDirectPlay4::EnumGroups により列挙される。IDirectPlay4::CreateGroupInGroup メソッドでは、親グループのサブグループとなるグループが作成される。

グループは、一般企業のアプリケーションでも使用できる。ロビー セッションでは、プレーヤーを収集するメカニズムとしてステージング領域を使用し、IDirectPlay4::StartSession を使用して新しいアプリケーション セッションを起動する。

グループを作成したプレーヤーが、そのデフォルトの所有者となる。名前やリモート データなどのグループ プロパティを変更できるのは、所有者だけである。所有者がセッションを抜けると、所有権はセッションのホストに移る。

セッション内のグループを認識しているプレーヤーであれば、グループのメンバを変更したり、グループを削除したりできる。

グループは、明示的に破棄されるまでセッション内に存続する。

必要条件

  Windows NT/2000 : Windows 2000 が必要。
  Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
  ヘッダー : dplay.h で宣言。
  インポート ライブラリ : dplayx.lib を使用。

参照

DPNAMEDPMSG_CREATEPLAYERORGROUPIDirectPlay4::AddGroupToGroupIDirectPlay4::DestroyGroupIDirectPlay4::EnumGroupsIDirectPlay4::EnumGroupPlayersIDirectPlay4::SendIDirectPlay4::SetGroupDataIDirectPlay4::SetGroupNameIDirectPlay4::CreateGroupInGroupIDirectPlay4::GetGroupFlags