bool NET_ReceiveDatagram(NET_DatagramSocket *sock, NET_Datagram **dgram);
| NET_DatagramSocket * | sock | データを受信するデータグラムソケット |
| NET_Datagram ** | dgram | データグラムパケットの代入先へのポインタ |
データグラムソケットでデータのパケットを送信する. パケットは完全に届く場合も全く届かない場合もある. それに対してストリームソケットはデータストリームを信頼できるものにするためにバイトが少しずつ届けられる.
この呼び出しは決してブロックしない. 新しい有効なデータを得られない状態で呼ぶと, 即座に真を戻す. 呼び出し側は後で再び試みることができる.
この関数の呼び出しに成功すると, 新しい有効なパケットがない場合でも真を戻すため, 新しいパケットが得られたかをチェックするには戻り値の成功と*dgramがNULLでないことを確認する必要がある.
受信したパケットが不要になったとき, NET_DestroyDatagramに渡す必要がある. 送信側のアドレスを長時間保存したい場合は, そのアドレスにNET_RefAddress()を呼びポインタを保持すると安全である. その場合はアドレスが不要になったときNET_UnrefAddress()を呼ぶ必要がある.
データグラムはネットワーク上の任意のアドレスとポートから予告なし到着するため, その情報はこの関数から得られるNET_Datagramオブジェクトに含まれている. そして, これが応答する相手を知るための唯一の手段である. 「サーバ」としてふるまう場合でなくても, 誰かがあなたのアプリケーションに送信すればパケットはソケットに到着する.
致命的なエラーが発生すると, この関数は偽を戻す. 「接続」のような失敗する状態がないためデータグラムソケットは通常は失敗を報告しないが, システムレベルの状態で回復不能な場合に失敗を報告する. ダイアグラムソケットが失敗した場合, これ以降は使用できないとみなし, NET_DestroyDatagramSocket()で破棄する必要がある.
同じソケットを複数のスレッドから同期を行わずに使用してはならない. しかし, 異なるスレッドから別々のソケットに同時にアクセスすることは問題ない.