bool NET_SendDatagram(NET_DatagramSocket *sock, NET_Address *address, Uint16 port, const void *buf, int buflen);
| NET_DatagramSocket * | sock | データを送信するデータグラムソケット |
| NET_Address * | address | アドレスのNET_Addressオブジェクト. NULLのときブロードキャスト |
| Uint16 | port | アドレスのポート |
| const void * | buf | 1つのパケットで送信するデータへのポインタ |
| int | buflen | 送信するデータのバイト数 |
データグラムソケットでデータのパケットを送信する. パケットは完全に届く場合も全く届かない場合もある. それに対してストリームソケットはデータストリームを信頼できるものにするためにバイトが少しずつ届けられる.
データグラムパケットは送信とは異なる順序で届く場合や, 伝送中にネットワークで失われることもある. このことをあらかじめ考慮しなければならない. さらに混乱することに, SDL_netは同じパケットを複数のインターフェースで送信する場合があり, 異なるネットワークアドレスから同じパケットを受信する場合がある. このことも考慮しなければならない.
ネットワーク上の任意のアドレスとポートに送信できるが, パケットが失われないようにするには送信先にデータを待つデータグラムソケットが存在している必要がある.
経験上, 1500バイトを超えるパケットをインターネットに送信するべきではない. これよりも大きなものは, ルータが分割したり失ったりする場合がある. しかし, SDL_netにはハードコードされた限界はなく, 条件が良ければさらに大きなデータも送ることができる場合もある.
この呼び出しは決してブロックしない. すぐにデータを送れない場合でも, ライブラリは後で送信するためにキューに入れる. キュー内に未送信のデータがあるかを知る方法はない. データグラム転送は信頼性が低く, キューのデータについて何らかの想定をしてはならない.
致命的なエラーが発生すると, この関数は偽を戻す. 「接続」のような失敗する状態がないためデータグラムソケットは通常は失敗を報告しないが, システムレベルの状態で回復不能な場合に失敗を報告する. ダイアグラムソケットが失敗した場合, これ以降は使用できないとみなし, NET_DestroyDatagramSocket()で破棄する必要がある.
NULLアドレスへの送信はパケットのブロードキャストとして扱われる. これはソケットがブロードキャストを許可して生成されていない場合, 即座に失敗を報告するので注意すること. ブロードキャストパケットはLAN上の全てのマシンに無条件に送信する(のみである).
警告: これを使用して全員が同一LAN上でプレーし, 全員が単純にパケットをブロードキャストするゲームを作成できる. しかし, これは絶対にすべきではない. ブロードキャストパケットは, 相手が望んでも望まなくてもLAN上の全てのデバイスに向かう. 全盛時代のDOOMは同じネットワーク上の多くのプレイヤーが絶えることなくブロードキャストしたため, ネットワーク全体がダウンするほどだった.
実際には, ブロードキャストは特定の場合の少量で行うのが有益である. 例えば, LANのみのクライアントが有効なサーバを探すために少量のパケットをブロードキャストし, 動作中のサーバがブロードキャストではなくクライアントに直接応答すれば合理的で安全である. クライアントとサーバがお互いを認識した後は, ブロードキャストを全く使用せずに直接通信を行うことができる. ピア・トゥ・ピアのゲームならば, 接続が成立した後は, 互いに認識したプレイヤーに個別のパケットを送るか, マルチキャストを使用する(これはブロードキャストと似ているが, 明示的にlistenしているデバイスのみ転送される)方が良い.
IPv6はブロードキャストに対応していないが, 特定のインターフェースまたはOSが選択したデフォルトの全ノードへのリンクローカルマルチキャストグループであるff02::1へのマルチキャストで模倣している. 将来的には他のプロトコルも同じような方法で疑似的にブロードキャストを行えるようになるかもしれない.
この関数はどのスレッドからも安全に呼べる.