NET_DatagramSocket * NET_CreateDatagramSocket(NET_Address *addr, Uint16 port, SDL_PropertiesID props);
| NET_Address * | addr | 接続をlistenするローカルアドレス. NULLのとき全ての有効なローカルアドレスでlistenする |
| Uint16 | port | 接続をlistenするローカルアドレスのポート. 0のときシステムが決める |
| SDL_PropertiesID | props | 新しいサーバのプロパティ. デフォルトのとき0 |
データグラムソケットはストリームソケットとは異なるルールに従う. これは信頼性の高いバイトストリームではなくパケットで, 1つのリモートシステムとの通信以外も行え, 切断の可能性のある単一の「接続」の維持が存在しない. そのため, 使い方は複雑になるがネットワークの障害に対応しやすい. アプリケーションにとってどちらが良いかは, 完全にアプリケーションの目的による.
データグラムソケットの考え方は, 送信データを1つのチャンク(「パケット」)として相手のアドレスに1つずつ送り, 受信側は, 後で送ったパケットを先に到着することや全く到着しないこともありデフォルトではそれがいつ起こったかを知る方法もないが, 到着したのを受信するというものである.
この関数は新しいデータグラムソケットを生成する.
システムは即座にソケットを生成できるか否かを判別できるため, この関数はブロックせず, また非同期処理も行わない. この関数が成功を戻した場合, すぐにネットワークとの通信を開始することができる.
接続をlistenするアドレスを指定することができる. このアドレスはシステムのローカルアドレスである必要があり, 恐らくNET_GetLocalAddresses()が戻したアドレスの1つだが, ほとんどの場合はアプリケーションが有効なアドレスでlistenするために単にNULLを指定すればよい.
特定のポートにバインドする必要がある場合(サーバのように), portを指定する必要がある. データグラムサーバは必ずこれを行い, 既知のポートに到着できるようにしなければならない.
単に通信を開始したい場合(クライアントのように), 0を指定してシステムに未使用のポートを選択させる必要がある.
あるポートに一度にバインドできるのは1つのアプリケーションのみのため, サーバのような動作を行わないならば, 0を選択すべきである.
データグラムソケットは個別のパケットをそれぞれのポートにも送ることができるため, これはソケットのデータがどのポートに届くかの選択をするだけである.
データグラムソケットは(UDPより上の)特定のプロトコルを使用していないため, SDL_netを使用していないアプリケーションとも通信できるが, WebRTCのような任意のバイトパケット以上のプロトコルで対話したい場合はデータグラムソケットの上に自分自身で実装しなければならない.
BSDソケットやWinSockとは異なり, ポートは通常の整数で指定する. ライブラリがアプリケーションの代わりに処理するため, バイト交換で「ネットワーク順」にする必要はない.
呼び出し側はプロパティで動作をカスタマイズできる.
これは任意で, propsを0にすると全てのプロパティをデフォルトにできる.
これらのプロパティに対応している:
NET_PROP_DATAGRAM_SOCKET_REUSEADDR_BOOLEAN: 真のとき, 以前のサーバがこのアドレスを使用中でもサーバを生成する.
様々な理由でネットワークはアプリケーションが同じアドレスを再び使用する間に待ち時間を設けようとするが, ソフトウェア開発や単にクラッシュしたサービスの再起動するためにlistenを高速に行いたい場合には問題となりうる.
このプロパティのデフォルトは真である(しかし, OSレベルではデフォルトは偽であることに注意すること).
このプロパティが偽でOSが十分な時間が経過していないと判断した場合, サーバの生成は失敗し, この関数はエラーを報告する.
NET_PROP_DATAGRAM_SOCKET_ALLOW_BROADCAST_BOOLEAN: 真のときソケットはブロードキャストを許可する.
低レベルでは, これはIPv4ソケットのSO_BROADCASTの設定で, OSレベルでサブネットのブロードキャストの送信を許可する.
IPv6では, 全ノードへのリンクローカルマルチキャストグループであるff02::1に参加し, そこへの送信とそこからの受信を許可することで通常のIPv4ブロードキャストを模倣する.
他のプロトコルでは似た動作を行うようにする.
このソケットでブロードキャストパケットの送受信を行わないならば, このプロパティを偽にするか, デフォルトは偽なので設定しないこと.
注意: IPv4はこのプロパティを設定しなくてもブロードキャストパケットの受信を行えるが, IPv6は行えない.
ブロードキャストアドレスへの送信はNET_SendDatagram()を参照すること.
この関数はどのスレッドからも安全に呼べる.