CTR NEX API Reference
nn::nex::DirectStream クラスabstract

複製オブジェクトを使用しない単純な送受信(ダイレクトストリーム)機能を扱うクラスです。 [詳解]

#include <NetZ/src/Core/DOCore/DirectStream.h>

nn::nex::SystemComponentを継承しています。

クラス

struct  Data
 DirectStreamでの受信情報です。 [詳解]
 

公開型

enum  StreamType {
  Unreliable,
  Reliable
}
 DirectStreamで扱う通信の種類です。 [詳解]
 

公開メンバ関数

 DirectStream ()
 このコンストラクタはアプリケーション側から直接呼び出さないでください。DirectStreamクラスのインスタンスは、システムによって自動的に生成されます。
 
virtual ~DirectStream ()
 このデストラクタはアプリケーション側から直接呼び出さないでください。DirectStreamクラスのインスタンスは、システムによって自動的に破棄されます。
 
RefCountedObjectAcquireRef ()
 参照カウントを 1 増加させます。
 
void Disable ()
 DirectStreamの機能を無効化します。 [詳解]
 
void Enable ()
 DirectStreamの機能を有効化します。 [詳解]
 
size_t GetMaxReliableSendBufferNum () const
 Reliable通信における最大送信バッファ数を取得します。 [詳解]
 
qInt32 GetPendingReliableBufferNum (StationID id, SubStreamID subStreamID=SubStreamIDDefine::SYSTEM)
 StationIDで指定されるStation宛のReliable通信の滞留数を取得します。 取得した値は、ダイレクトストリームを使用したReliable通信以外に、NEX内部で使用されるReliable通信のパケットも含まれます。 [詳解]
 
void GetReceivedData (qVector< DirectStream::Data > &recvData)
 ディスパッチ処理によって受信バッファに蓄積された受信データを取得します。 [詳解]
 
void ReleaseRef ()
 参照カウントを 1 減少させます。0 になるときに自分自身を delete します。
 
qResult Send (StationID id, StreamType type, const qByte *pBuffer, size_t size)
 特定のステーションへデータを送信します。 [詳解]
 
qBool Send (CallContext *pContext, StationID id, StreamType type, const qByte *pBuffer, size_t size)
 特定のステーションへデータを送信します。 [詳解]
 
qResult SendAll (StreamType type, const qByte *pBuffer, size_t size)
 セッション参加中の全ステーションへデータを送信します。 [詳解]
 
qResult SendReliable (StationID id, SubStreamID subStreamID, const qByte *pBuffer, size_t size)
 特定のステーションへSubStreamIDを指定したReliableデータを送信します。 [詳解]
 
qBool SendReliable (CallContext *pContext, StationID id, SubStreamID subStreamID, const qByte *pBuffer, size_t size)
 特定のステーションへSubStreamIDを指定したReliableデータを送信します。 [詳解]
 
qResult SendUnreliable (StationID id, const qByte *pBuffer, size_t size)
 特定のステーションへUnreliableデータを送信します。 [詳解]
 
qResult SendUnreliableAll (const qByte *pBuffer, size_t size)
 セッション参加中の全ステーションへUnreliableデータを送信します。 [詳解]
 
void SetMaxReliableSendBufferNum (size_t bufferNum)
 Reliable通信における最大送信バッファ数を設定します。 [詳解]
 

静的公開メンバ関数

static DirectStreamGetInstance ()
 DirectStreamのインスタンスを取得します。 [詳解]
 

詳解

複製オブジェクトを使用しない単純な送受信(ダイレクトストリーム)機能を扱うクラスです。

列挙型メンバ詳解

DirectStreamで扱う通信の種類です。

列挙値
Unreliable 

非信頼性通信

Reliable 

信頼性通信

関数詳解

static DirectStream* nn::nex::DirectStream::GetInstance ( )
static

DirectStreamのインスタンスを取得します。

NetZが生成されていない状態では、NULLとなります。 NetZオブジェクトが正常に生成されていれば、本関数の返り値はNULLでないことを期待できます。

戻り値
DirectStreamオブジェクトへのポインタが返ります。
void nn::nex::DirectStream::Enable ( )

DirectStreamの機能を有効化します。

ダイレクトストリームを使用して送受信を行う前に必ず呼び出してください。
有効化してない状態では送信処理はエラーを返します。
有効化するまでに受信したパケットはライブラリ内で破棄されます。

void nn::nex::DirectStream::Disable ( )

DirectStreamの機能を無効化します。

無効化しても、すでに送信用キューに蓄積された送信データがあれば引き続き送信され続けます。 受信においてはReliable通信に対する到達確認の応答がライブラリ内部で行われます。

qResult nn::nex::DirectStream::Send ( StationID  id,
StreamType  type,
const qByte pBuffer,
size_t  size 
)

特定のステーションへデータを送信します。

StationIDはStation::GetStationID で取得できます。 Reliable通信を指定した送信では、送信バッファに空きがない場合にReliableSendBufferFullエラーを返します。 これは一時的に送信バッファの上限に達したことを示すエラーであるため、 ReliableSendBufferFullが発生した場合は、ディスパッチを行い時間をおいてから再度送信を行ってください。

パケットバッファに空きがない場合PacketBufferFullエラーを返します。 これは一時的にパケットバッファが不足していることを示すエラーであるため、 ディスパッチを行い時間をおいてから再度送信を行ってください。 高頻度でPacketBufferFullが発生する場合は、パケットバッファを増やす対策も行ってください。 パケットバッファの設定については、PacketBufferManager を参照してください。

引数
[in]id宛先のステーションのStationIDを指定します。
[in]type通信の種類を指定します。
[in]pBuffer送信するデータを指定します。
[in]size送信するデータのサイズを指定します。Reliable通信では32768以下、それ以外の通信では1300(P2Pトポロジー以外の場合は1250)以下となるようにしてください。
戻り値一覧:

"QSUCCESS(Core, Success)" 送信リクエストが成功した場合

"QERROR(Core, InvalidSequence)" ダイレクトストリームを有効化してない場合

"QERROR(Transport, Unknown)" PRUDPUserProtocol::GetInstance()がNULLの場合

"QERROR(Core, CallInitiationFailure)" 呼び出しコンテキストの初期化に失敗した場合

"QERROR(Core, InvalidArgument)" 引数の値が不正の場合 (pBufferがNULLであるか、sizeが超過しています。)

"QERROR(Transport, ConnectionFailure)" 宛先Stationとの接続が確立されていなかった場合

"QERROR(Transport, InvalidStation)" 宛先Stationが存在しなかった場合 (接続処理中であるか、すでに存在していません。)

"QERROR(Transport, ReliableSendBufferFull)" Reliable通信の送信バッファが一杯の場合。アプリケーションによるハンドリングが必要です。(本関数でこのエラーが返っても NetZ::GetFatalError で取得できるフェイタルエラーにはセットされません)

"QERROR(Transport, PacketBufferFull)" パケットバッファ枯渇により送信できなかった場合。アプリケーションによるハンドリングが必要です。 (本関数でこのエラーが返っても NetZ::GetFatalError で取得できるフェイタルエラーにはセットされません)

qBool nn::nex::DirectStream::Send ( CallContext pContext,
StationID  id,
StreamType  type,
const qByte pBuffer,
size_t  size 
)

特定のステーションへデータを送信します。

呼び出しコンテキストを指定することで、Reliable通信の到達確認を非同期処理で検知することができます。 Reliable通信の場合、到達確認ができた場合にSuccessとなります。到達確認ができるまでは完了しません。 Reliable通信以外では、呼び出しコンテキストは呼び出し終了時点で完了状態となります。 呼び出しコンテキストをキャンセルしても、送信リクエストが成功したReliable通信の送信は継続されます。
StationIDはStation::GetStationID で取得できます。 呼び出しコンテキストが終了した時の処理結果は、CallContext::GetOutcome で取得できます。 呼び出しコンテキストの処理結果については、返り値qResult型のSend の返り値を参照してください。

引数
[in,out]pContext呼び出しコンテキストを指定します。
[in]id宛先のステーションのStationIDを指定します。
[in]type通信の種類を指定します。
[in]pBuffer送信するデータを指定します。
[in]size送信するデータのサイズを指定します。Reliable通信では32768以下、それ以外の通信では1300(P2Pトポロジー以外の場合は1250)以下となるようにしてください。
戻り値一覧:

true 送信リクエストが成功した場合

false 送信リクエストが失敗した場合

qResult nn::nex::DirectStream::SendUnreliable ( StationID  id,
const qByte pBuffer,
size_t  size 
)

特定のステーションへUnreliableデータを送信します。

StationIDはStation::GetStationID で取得できます。

パケットバッファに空きがない場合PacketBufferFullエラーを返します。 これは一時的にパケットバッファが不足していることを示すエラーであるため、 必要に応じてパケットバッファを増やしてください。パケットバッファの設定については、PacketBufferManager を参照してください。

引数
[in]id宛先のステーションのStationIDを指定します。
[in]pBuffer送信するデータを指定します。
[in]size送信するデータのサイズを指定します。1300(P2Pトポロジー以外の場合は1250)以下となるようにしてください。
戻り値一覧:

"QSUCCESS(Core, Success)" 送信リクエストが成功した場合

"QERROR(Core, InvalidSequence)" ダイレクトストリームを有効化してない場合

"QERROR(Transport, Unknown)" PRUDPUserProtocol::GetInstance()がNULLの場合

"QERROR(Core, CallInitiationFailure)" 呼び出しコンテキストの初期化に失敗した場合

"QERROR(Core, InvalidArgument)" 引数の値が不正の場合 (pBufferがNULLであるか、sizeが超過しています。)

"QERROR(Transport, ConnectionFailure)" 宛先Stationとの接続が確立されていなかった場合

"QERROR(Transport, InvalidStation)" 宛先Stationが存在しなかった場合 (接続処理中であるか、すでに存在していません。)

"QERROR(Transport, PacketBufferFull)" パケットバッファ枯渇により送信できなかった場合。アプリケーションによるハンドリングが必要です。 (本関数でこのエラーが返っても NetZ::GetFatalError で取得できるフェイタルエラーにはセットされません)

qResult nn::nex::DirectStream::SendReliable ( StationID  id,
SubStreamID  subStreamID,
const qByte pBuffer,
size_t  size 
)

特定のステーションへSubStreamIDを指定したReliableデータを送信します。

StationIDはStation::GetStationID で取得できます。   送信バッファに空きがない場合にReliableSendBufferFullエラーを返します。 これは一時的に送信バッファの上限に達したことを示すエラーであるため、 ReliableSendBufferFullが発生した場合は、ディスパッチを行い時間をおいてから再度送信を行ってください。

パケットバッファに空きがない場合PacketBufferFullエラーを返します。 これは一時的にパケットバッファが不足していることを示すエラーであるため、 ディスパッチを行い時間をおいてから再度送信を行ってください。 高頻度でPacketBufferFullが発生する場合は、パケットバッファを増やす対策も行ってください。 パケットバッファの設定については、PacketBufferManager を参照してください。

引数
[in]id宛先のステーションのStationIDを指定します。
[in]subStreamID送信に利用するSubStreamIDを指定します。 SubStreamIDDefine::SYSTEMは、システムと共有で、 SendでReliable通信を行った場合と同等です。
[in]pBuffer送信するデータを指定します。
[in]size送信するデータのサイズを指定します。Reliable通信では32768以下、それ以外の通信では1300(P2Pトポロジー以外の場合は1250)以下となるようにしてください。
戻り値一覧:

"QSUCCESS(Core, Success)" 送信リクエストが成功した場合

"QERROR(Core, InvalidSequence)" ダイレクトストリームを有効化してない場合

"QERROR(Transport, Unknown)" PRUDPUserProtocol::GetInstance()がNULLの場合

"QERROR(Core, CallInitiationFailure)" 呼び出しコンテキストの初期化に失敗した場合

"QERROR(Core, InvalidArgument)" 引数の値が不正の場合 (pBufferがNULLであるか、sizeが超過しています。)

"QERROR(Transport, ConnectionFailure)" 宛先Stationとの接続が確立されていなかった場合

"QERROR(Transport, InvalidStation)" 宛先Stationが存在しなかった場合 (接続処理中であるか、すでに存在していません。)

"QERROR(Transport, ReliableSendBufferFull)" Reliable通信の送信バッファが一杯の場合(本関数でこのエラーが返っても NetZ::GetFatalError で取得できるフェイタルエラーにはセットされません)

"QERROR(Transport, InvalidSubStreamID)" 指定されたSubStreamIDが無効なIDの場合。相手のステーションが受け付けることができないSubStreamIDの場合も発生します。

"QERROR(Transport, PacketBufferFull)" パケットバッファ枯渇により送信できなかった場合。アプリケーションによるハンドリングが必要です。 (本関数でこのエラーが返っても NetZ::GetFatalError で取得できるフェイタルエラーにはセットされません)

参照
SubStreamIDDefine, StreamSettings::SetMaxUserReliableSubStreams()
qBool nn::nex::DirectStream::SendReliable ( CallContext pContext,
StationID  id,
SubStreamID  subStreamID,
const qByte pBuffer,
size_t  size 
)

特定のステーションへSubStreamIDを指定したReliableデータを送信します。

呼び出しコンテキストを指定することで、Reliable通信の到達確認を非同期処理で検知することができます。 到達確認ができた場合にSuccessとなります。到達確認ができるまでは完了しません。 呼び出しコンテキストをキャンセルしても、送信リクエストが成功したReliable通信の送信は継続されます。
StationIDはStation::GetStationID で取得できます。 呼び出しコンテキストが終了した時の処理結果は、CallContext::GetOutcome で取得できます。 呼び出しコンテキストの処理結果については、返り値qResult型のSendReliable の返り値を参照してください。

引数
[in,out]pContext呼び出しコンテキストを指定します。
[in]id宛先のステーションのStationIDを指定します。
[in]subStreamID送信に利用するSubStreamIDを指定します。 SubStreamIDDefine::SYSTEMは、システムと共有で、 SendでReliable通信を行った場合と同等です。
[in]pBuffer送信するデータを指定します。
[in]size送信するデータのサイズを指定します。Reliable通信では32768以下、それ以外の通信では1300(P2Pトポロジー以外の場合は1250)以下となるようにしてください。
戻り値一覧:

true 送信リクエストが成功した場合

false 送信リクエストが失敗した場合

参照
SubStreamIDDefine, StreamSettings::SetMaxUserReliableSubStreams()
qResult nn::nex::DirectStream::SendAll ( StreamType  type,
const qByte pBuffer,
size_t  size 
)

セッション参加中の全ステーションへデータを送信します。

パケットバッファに空きがない場合PacketBufferFullエラーを返します。 これは一時的にパケットバッファが不足していることを示すエラーであるため、 ディスパッチを行い時間をおいてから再度送信を行ってください。 高頻度でPacketBufferFullが発生する場合は、パケットバッファを増やす対策も行ってください。 パケットバッファの設定については、PacketBufferManager を参照してください。

引数
[in]type通信の種類を指定します。Reliable通信は指定できません。
[in]pBuffer送信するデータを指定します。
[in]size送信するデータのサイズを指定します。1300(P2Pトポロジー以外の場合は1250)以下となるようにしてください。
戻り値一覧:

"QSUCCESS(Core, Success)" 送信リクエストが成功した場合

"QERROR(Core, InvalidSequence)" ダイレクトストリームを有効化してない場合

"QERROR(Transport, Unknown)" PRUDPUserProtocol::GetInstance()がNULLの場合

"QERROR(Core, InvalidArgument)" 引数の値が不正の場合 (pBufferがNULLであるか、sizeが超過しています。)

"QERROR(Transport, ConnectionFailure)" 送信成功したステーションが一台も存在しなかった場合

"QERROR(Transport, PacketBufferFull)" パケットバッファ枯渇により送信できなかった場合。アプリケーションによるハンドリングが必要です。 (本関数でこのエラーが返っても NetZ::GetFatalError で取得できるフェイタルエラーにはセットされません)

qResult nn::nex::DirectStream::SendUnreliableAll ( const qByte pBuffer,
size_t  size 
)

セッション参加中の全ステーションへUnreliableデータを送信します。

パケットバッファに空きがない場合PacketBufferFullエラーを返します。 これは一時的にパケットバッファが不足していることを示すエラーであるため、 必要に応じてパケットバッファを増やしてください。パケットバッファの設定については、PacketBufferManager を参照してください。

引数
[in]pBuffer送信するデータを指定します。
[in]size送信するデータのサイズを指定します。1300(P2Pトポロジー以外の場合は1250)以下となるようにしてください。
戻り値一覧:

"QSUCCESS(Core, Success)" 送信リクエストが成功した場合

"QERROR(Core, InvalidSequence)" ダイレクトストリームを有効化してない場合

"QERROR(Transport, Unknown)" PRUDPUserProtocol::GetInstance()がNULLの場合

"QERROR(Core, InvalidArgument)" 引数の値が不正の場合 (pBufferがNULLであるか、sizeが超過しています。)

"QERROR(Transport, ConnectionFailure)" 送信成功したステーションが一台も存在しなかった場合

"QERROR(Transport, PacketBufferFull)" パケットバッファ枯渇により送信できなかった場合。アプリケーションによるハンドリングが必要です。 (本関数でこのエラーが返っても NetZ::GetFatalError で取得できるフェイタルエラーにはセットされません)

void nn::nex::DirectStream::GetReceivedData ( qVector< DirectStream::Data > &  recvData)

ディスパッチ処理によって受信バッファに蓄積された受信データを取得します。

本関数を呼び出すまで、ディスパッチによって受信バッファにデータが蓄積されます。 本関数呼び出しで受信データを取得することで、受信バッファはクリアされます。 本関数を呼び出しせずに、受信バッファにデータが蓄積され続けると、受信バッファの上限に達した時に、 受信あふれとしてNetZ::GetFatalError で、QERROR(Transport, NoBuffer)のフェイタルエラーが発生します。 受信あふれが起こる場合は、他Stationからの送信数を減らすように設計するか、 Scheduler::Dispatch またはScheduler::DispatchAll とともに本関数の呼び出し頻度を増やしてください。

引数
[out]recvData受信済みデータの格納先を指定します。
size_t nn::nex::DirectStream::GetMaxReliableSendBufferNum ( ) const

Reliable通信における最大送信バッファ数を取得します。

送信処理で蓄積された送信バッファ数が本設定値にまで達していた場合、送信処理はReliableSendBufferFullのエラーを返します。
初期値は48です。

戻り値
Reliable通信における最大送信バッファ数を返します。
void nn::nex::DirectStream::SetMaxReliableSendBufferNum ( size_t  bufferNum)

Reliable通信における最大送信バッファ数を設定します。

送信処理で蓄積された送信バッファ数が本設定値にまで達していた場合、送信処理はReliableSendBufferFullのエラーを返します。
蓄積された送信バッファ数がライブラリの上限を超える場合は、NetZ::GetFatalError でReliableSendBufferFullFatalのフェイタルエラーが発生しますので、 設定の最大値は96程度を目安としてください。

引数
[in]bufferNumReliable通信における最大送信バッファ数を指定します。
qInt32 nn::nex::DirectStream::GetPendingReliableBufferNum ( StationID  id,
SubStreamID  subStreamID = SubStreamIDDefine::SYSTEM 
)

StationIDで指定されるStation宛のReliable通信の滞留数を取得します。 取得した値は、ダイレクトストリームを使用したReliable通信以外に、NEX内部で使用されるReliable通信のパケットも含まれます。

引数
[in]idReliable通信の滞留数を取得する対象ステーションのStationIDを指定します。
[in]subStreamID複数本Reliableを使う時のIDを指定します。省略時は、 SubStreamIDDefine::SYSTEMが指定されて、システムと共用になります。
戻り値
StationID で指定される Station 宛の Reliable 通信の滞留数が返ります。ローカルステーション、切断された Station、存在しない Station や存在しない SubStreamID を指定した場合は -1 が返ります。
参照
SubStreamIDDefine, StreamSettings::SetMaxUserReliableSubStreams()