int NET_ReadFromStreamSocket(NET_StreamSocket *sock, void *buf, int buflen);
| NET_StreamSocket * | sock | データを通して受信するストリームソケット |
| void * | buf | 受信したデータの書き込み先へのポインタ |
| int | buflen | bufが示すバッファのバイト数. これがストリームソケットの読み込みの最大値となる |
buflenより少ない場合や, 有効なデータがない場合は0もありうる). 失敗のとき-1を戻す.
SDL_GetError()を呼んで詳細を知ることができる.
ストリームソケットは, データは送信した順序で到着し, 到着を保証するために必要ならばシステムが再送するため, 信頼性が高い. つまり, 致命的な問題がなければデータは大幅な遅れが生じることがあっても到着する. しかし「致命的な問題」は珍しいことではない.
(これはデータグラムソケットとは対照的で, こちらはデータのチャンクが不定な順序で届く場合や全く届かない場合があるが, 失われたチャンクが現れるまで待つことは決してない.)
ストリームソケットは双方向である. 読み込みと書き込みを同じストリームで行い, もう一方の接続先も同じことができる.
この関数はストリームソケットで到着したがまだ読み込んでいないデータを戻す. データはリモート側が送信した順序で提供される. この関数は, その時点で利用可能なデータの量により, 要求よりも少ないデータを戻す場合がある. また, アプリケーションは利用可能な全てのデータを一度に要求する必要はない.
この呼び出しは決してブロックしない. 新しい有効なデータを得られない状態で呼ぶと, 即座に0を戻す. 呼び出し側は後で再び試みることができる.
接続に失敗すると(リモート側の切断や, 様々な種類のネットワーク障害の発生により), この関数は-1を戻して失敗を報告する. ストリームソケットが失敗を報告するのは回復不能な場合のみであるため, 一度ソケットが失敗すると使用することはできないとみなし, NET_DestroyStreamSocket()で破棄する必要がある.
同じソケットを複数のスレッドから同期を行わずに使用してはならない. しかし, 異なるスレッドから別々のソケットに同時にアクセスすることは問題ない.