`uv_udp_t` — UDPハンドル¶

UDPハンドルは、クライアントとサーバーの両方のUDP通信をカプセル化します。

データ型¶

type uv_udp_t¶: UDPハンドルの型です。

type uv_udp_send_t¶: UDP送信要求の型です。

enum uv_udp_flags¶

次の関数とコールバックで使うフラグです: uv_udp_bind()およびuv_udp_recv_cb。

enum uv_udp_flags {
    /* Disables dual stack mode. */
    UV_UDP_IPV6ONLY = 1,
    /*
     * Indicates message was truncated because read buffer was too small. The
     * remainder was discarded by the OS. Used in uv_udp_recv_cb.
     */
    UV_UDP_PARTIAL = 2,
    /*
     * Indicates if SO_REUSEADDR will be set when binding the handle.
     * This sets the SO_REUSEPORT socket flag on the BSDs (except for
     * DragonFlyBSD), OS X, and other platforms where SO_REUSEPORTs don't
     * have the capability of load balancing, as the opposite of what
     * UV_UDP_REUSEPORT would do. On other Unix platforms, it sets the
     * SO_REUSEADDR flag. What that means is that multiple threads or
     * processes can bind to the same address without error (provided
     * they all set the flag) but only the last one to bind will receive
     * any traffic, in effect "stealing" the port from the previous listener.
     */
    UV_UDP_REUSEADDR = 4,
    /*
     * Indicates that the message was received by recvmmsg, so the buffer provided
     * must not be freed by the recv_cb callback.
     */
    UV_UDP_MMSG_CHUNK = 8,
    /*
     * Indicates that the buffer provided has been fully utilized by recvmmsg and
     * that it should now be freed by the recv_cb callback. When this flag is set
     * in uv_udp_recv_cb, nread will always be 0 and addr will always be NULL.
     */
    UV_UDP_MMSG_FREE = 16,
    /*
     * Indicates if IP_RECVERR/IPV6_RECVERR will be set when binding the handle.
     * This sets IP_RECVERR for IPv4 and IPV6_RECVERR for IPv6 UDP sockets on
     * Linux. This stops the Linux kernel from suppressing some ICMP error messages
     * and enables full ICMP error reporting for faster failover.
     * This flag is no-op on platforms other than Linux.
     */
    UV_UDP_LINUX_RECVERR = 32,
    /*
     * Indicates if SO_REUSEPORT will be set when binding the handle.
     * This sets the SO_REUSEPORT socket option on supported platforms.
     * Unlike UV_UDP_REUSEADDR, this flag will make multiple threads or
     * processes that are binding to the same address and port "share"
     * the port, which means incoming datagrams are distributed across
     * the receiving sockets among threads or processes.
     *
     * This flag is available only on Linux 3.9+, DragonFlyBSD 3.6+,
     * FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ for now.
     */
    UV_UDP_REUSEPORT = 64,
    /*
     * Indicates that recvmmsg should be used, if available. The uv_alloc_cb
     * for this handle should create buffers that are multiples of 64 KiB.
     */
    UV_UDP_RECVMMSG = 256
};

typedef void (*uv_udp_send_cb)(uv_udp_send_t *req, int status)¶: 次の関数へ渡すコールバックの型定義です: uv_udp_send()。データの送信後に呼び出します。

typedef void (*uv_udp_recv_cb)(uv_udp_t *handle, ssize_t nread, const uv_buf_t *buf, const struct sockaddr *addr, unsigned flags)¶

次の関数へ渡すコールバックの型定義です: uv_udp_recv_start()。エンドポイントがデータを受信したときに呼び出します。

handle: UDPハンドル。
nread: 受信したバイト数です。読み取るデータがなくなると0になります。0は空のデータグラムの受信を示す場合もあります（この場合、addrはNULLではありません）。伝送エラーを検出すると0未満になります。次の関数、recvmmsg(2)を使っている場合、それ以上のチャンクは受信せず、バッファを安全に解放できます。
buf: uv_buf_t型の受信データを格納したバッファです。
addr: struct sockaddr*型の、送信元アドレスを格納した構造体です。NULLの場合もあります。コールバックの実行中だけ有効です。
flags: 1つ以上のUV_UDP_*定数をORで組み合わせたものです。

バッファを解放する責任は呼び出された側にあり、libuvは再利用しません。エラー時には、次の条件を満たすヌルバッファの場合があります: buf->base == NULLかつbuf->len == 0。

次の関数、recvmmsg(2)を使う場合、各チャンクにはUV_UDP_MMSG_CHUNKフラグが設定されており、解放してはいけません。エラーがなければ、最後に次の条件のコールバックを呼び出します: nreadは0、addrはNULL、バッファは最初に確保したデータを指し、UV_UDP_MMSG_CHUNKフラグは解除され、UV_UDP_MMSG_FREEフラグが設定されます。UDPソケットエラーが起きると、nreadは0未満になります。どちらの場合も、呼び出された側は渡されたバッファを安全に解放できます。

バージョン1.40.0での変更: 次のフラグを追加しました: UV_UDP_MMSG_FREE。

注記

受信コールバックは、読み取るデータがないときにはnread == 0かつaddr == NULLで呼び出します。空のUDPパケットを受信したときにはnread == 0かつaddr != NULLで呼び出します。

enum uv_membership¶

マルチキャストアドレスのメンバーシップの型です。

typedef enum {
    UV_LEAVE_GROUP = 0,
    UV_JOIN_GROUP
} uv_membership;

公開メンバー¶

size_t uv_udp_t.send_queue_size¶: 送信待ちキューに入っているバイト数です。このフィールドは、現在キューに入っている情報量だけを示します。

size_t uv_udp_t.send_queue_count¶: 現在キューに入り、処理を待っている送信要求の数です。

uv_udp_t *uv_udp_send_t.handle¶: この送信要求を実行しているUDPハンドルです。

API¶

int uv_udp_init(uv_loop_t *loop, uv_udp_t *handle)¶: 新しいUDPハンドルを初期化します。実際のソケットは必要になるまで作成しません。成功時は0を返します。

int uv_udp_init_ex(uv_loop_t *loop, uv_udp_t *handle, unsigned int flags)¶

指定したフラグでハンドルを初期化します。次のパラメーター、flagsの下位8ビットをソケットドメインとして使い、そのドメインのソケットを作成します。指定したドメインがAF_UNSPECなら、次の関数と同じく、ソケットは作成しません: uv_udp_init()。

残りのビットには、次のフラグを設定できます:

UV_UDP_RECVMMSG: 設定していて、プラットフォームがサポートしていれば、recvmmsg(2)を使います。このハンドルのuv_alloc_cbは、64 KiBの倍数のバッファを作成してください。

バージョン1.7.0で追加。

バージョン1.37.0での変更: 次のフラグを追加しました: UV_UDP_RECVMMSG。

int uv_udp_open_ex(uv_udp_t *handle, uv_os_sock_t sock, unsigned int flags)¶

既存のファイルディスクリプターまたはWindows SOCKETをUDPハンドルとして開きます。

パラメーター:

handle – UDPハンドルです。次の関数で初期化しておく必要があります: uv_udp_init()。
sock – ハンドルに関連付ける既存のソケットです。
flags – ソケットの動作を制御するフラグです。UV_UDP_REUSEADDRおよびUV_UDP_REUSEPORTをサポートしています。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

バージョン1.52.0で追加。

int uv_udp_open(uv_udp_t *handle, uv_os_sock_t sock)¶

既存のファイルディスクリプターまたはWindows SOCKETをUDPハンドルとして開きます。

Unixだけ: sock引数の唯一の要件は、データグラムの契約に従うことです（未接続モードで動作し、sendmsg()/recvmsg()をサポートするなど）。つまり、rawソケットやnetlinkソケットなど、ほかのデータグラム型ソケットも渡せます。

バージョン1.2.1での変更: ファイルディスクリプターを非ブロッキングモードに設定するようになりました。

注記

渡されたファイルディスクリプターまたはSOCKETの型は検査しませんが、有効なデータグラムソケットを表す必要があります。

内部でSO_REUSEADDRソケットオプションを無条件に設定します。つまり、ユーザーの意図にかかわらず再利用フラグは常に有効です。より細かく制御するには、次の関数を使ってください: uv_udp_open_ex()。

int uv_udp_bind(uv_udp_t *handle, const struct sockaddr *addr, unsigned int flags)¶

UDPハンドルをIPアドレスとポートへバインドします。

パラメーター:

handle – UDPハンドルです。次の関数で初期化しておく必要があります: uv_udp_init()。
addr – struct sockaddr_inまたはstruct sockaddr_in6型の、バインド先アドレスとポートを格納した構造体です。
flags – ソケットのバインド方法を指定します。UV_UDP_IPV6ONLY, UV_UDP_REUSEADDR, UV_UDP_REUSEPORTおよびUV_UDP_RECVERRをサポートしています。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

バージョン1.49.0での変更: 次のフラグを追加しました: UV_UDP_REUSEPORT。

注記

UV_UDP_REUSEPORTフラグは、現在、Linux 3.9以降、DragonFlyBSD 3.6以降、FreeBSD 12.0以降、Solaris 11.4、AIX 7.2.5以降だけで利用できます。それ以外ではUV_ENOTSUPエラーを返します。負荷分散機能があるプラットフォームでは、SO_REUSEPORT`sについて、flagsに``UV_UDP_REUSEADDR`とUV_UDP_REUSEPORTを同時に指定できます。この場合、SO_REUSEPORTの動作が常にSO_REUSEADDRより優先されます。負荷分散機能がないプラットフォームでは、SO_REUSEPORT`sについて、flagsに``UV_UDP_REUSEADDR`とUV_UDP_REUSEPORTを同時に指定すると、UV_ENOTSUPエラーで失敗します。

int uv_udp_connect(uv_udp_t *handle, const struct sockaddr *addr)¶

UDPハンドルをリモートアドレスとポートに関連付けます。このハンドルから送るすべてのメッセージは、その宛先へ自動的に送信されます。切断するには次の組み合わせを指定します: NULL addr（addrにNULLを指定します）。すでに接続済みのハンドルでuv_udp_connect()を呼び出すと、UV_EISCONNエラーになります。未接続のハンドルを切断しようとすると、UV_ENOTCONNエラーを返します。

パラメーター:

handle – UDPハンドルです。次の関数で初期化しておく必要があります: uv_udp_init()。
addr – struct sockaddr_inまたはstruct sockaddr_in6型の、関連付けるアドレスとポートを格納した構造体です。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

バージョン1.27.0で追加。

int uv_udp_getpeername(const uv_udp_t *handle, struct sockaddr *name, int *namelen)¶

接続済みのUDPハンドルのリモートIPとポートを取得します。未接続の場合は、次のエラーを返します: UV_ENOTCONN。

パラメーター:

handle – UDPハンドルです。次の関数、uv_udp_init()で初期化し、バインドしておく必要があります。
name – アドレスデータを格納する構造体へのポインターです。IPv4とIPv6をサポートするには、struct sockaddr_storageを使ってください。
namelen – 入力時には、次のフィールドのデータを示します: name。出力時には、そのうちどれだけ格納したかを示します。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

バージョン1.27.0で追加。

int uv_udp_getsockname(const uv_udp_t *handle, struct sockaddr *name, int *namelen)¶

UDPハンドルのローカルIPとポートを取得します。

パラメーター:

handle – UDPハンドルです。次の関数、uv_udp_init()で初期化し、バインドしておく必要があります。
name – アドレスデータを格納する構造体へのポインターです。IPv4とIPv6をサポートするには、struct sockaddr_storageを使ってください。
namelen – 入力時には、次のフィールドのデータを示します: name。出力時には、そのうちどれだけ格納したかを示します。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

int uv_udp_set_membership(uv_udp_t *handle, const char *multicast_addr, const char *interface_addr, uv_membership membership)¶

マルチキャストアドレスのメンバーシップを設定します。

パラメーター:

handle – UDPハンドルです。次の関数で初期化しておく必要があります: uv_udp_init()。
multicast_addr – メンバーシップを設定するマルチキャストアドレスです。
interface_addr – インターフェイスのアドレスです。
membership – 次のいずれかを指定してください: UV_JOIN_GROUPまたはUV_LEAVE_GROUP。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

int uv_udp_set_source_membership(uv_udp_t *handle, const char *multicast_addr, const char *interface_addr, const char *source_addr, uv_membership membership)¶

送信元を指定するマルチキャストグループのメンバーシップを設定します。

パラメーター:

handle – UDPハンドルです。次の関数で初期化しておく必要があります: uv_udp_init()。
multicast_addr – メンバーシップを設定するマルチキャストアドレスです。
interface_addr – インターフェイスのアドレスです。
source_addr – 送信元アドレスです。
membership – 次のいずれかを指定してください: UV_JOIN_GROUPまたはUV_LEAVE_GROUP。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

バージョン1.32.0で追加。

int uv_udp_set_multicast_loop(uv_udp_t *handle, int on)¶

IPマルチキャストのループフラグを設定します。マルチキャストパケットをローカルソケットへループバックさせます。

パラメーター:

handle – UDPハンドルです。次の関数、uv_udp_init_ex()でAF_INETまたはAF_INET6を指定して初期化するか、次の関数、uv_udp_bind()でアドレスへ明示的にバインドするか、次の関数、uv_udp_send()またはuv_udp_recv_start()で暗黙にバインドしておく必要があります。
on – 有効にするには1、無効にするには0を指定します。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

int uv_udp_set_multicast_ttl(uv_udp_t *handle, int ttl)¶

マルチキャストのTTLを設定します。

パラメーター:

handle – UDPハンドルです。次の関数、uv_udp_init_ex()でAF_INETまたはAF_INET6を指定して初期化するか、次の関数、uv_udp_bind()でアドレスへ明示的にバインドするか、次の関数、uv_udp_send()またはuv_udp_recv_start()で暗黙にバインドしておく必要があります。
ttl – 1から255です。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

int uv_udp_set_multicast_interface(uv_udp_t *handle, const char *interface_addr)¶

データを送受信するマルチキャストインターフェイスを設定します。

パラメーター:

handle – UDPハンドルです。次の関数、uv_udp_init_ex()でAF_INETまたはAF_INET6を指定して初期化するか、次の関数、uv_udp_bind()でアドレスへ明示的にバインドするか、次の関数、uv_udp_send()またはuv_udp_recv_start()で暗黙にバインドしておく必要があります。
interface_addr – インターフェイスのアドレスです。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

int uv_udp_set_broadcast(uv_udp_t *handle, int on)¶

ブロードキャストを有効または無効にします。

パラメーター:

handle – UDPハンドルです。次の関数、uv_udp_init_ex()でAF_INETまたはAF_INET6を指定して初期化するか、次の関数、uv_udp_bind()でアドレスへ明示的にバインドするか、次の関数、uv_udp_send()またはuv_udp_recv_start()で暗黙にバインドしておく必要があります。
on – 有効にするには1、無効にするには0を指定します。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

int uv_udp_set_ttl(uv_udp_t *handle, int ttl)¶

生存時間（TTL）を設定します。

パラメーター:

handle – UDPハンドルです。次の関数、uv_udp_init_ex()でAF_INETまたはAF_INET6を指定して初期化するか、次の関数、uv_udp_bind()でアドレスへ明示的にバインドするか、次の関数、uv_udp_send()またはuv_udp_recv_start()で暗黙にバインドしておく必要があります。
ttl – 1から255です。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

int uv_udp_send(uv_udp_send_t *req, uv_udp_t *handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr *addr, uv_udp_send_cb send_cb)¶

UDPソケットでデータを送信します。ソケットを事前に次の関数、uv_udp_bind()でバインドしていなければ、0.0.0.0（すべてのインターフェイスを表すIPv4アドレス）とランダムなポート番号へバインドします。

Windowsでは、addrが未指定アドレス（0.0.0.0または::）を指すよう初期化されている場合、localhostを指すよう変更します。これはLinuxの動作に合わせるためです。

接続済みのUDPハンドルでは、addrをNULLに設定してください。それ以外はUV_EISCONNエラーを返します。

未接続のUDPハンドルでは、addrをNULLにできません。そうするとUV_EDESTADDRREQエラーを返します。

パラメーター:

req – UDP要求ハンドルです。初期化は不要です。
handle – UDPハンドルです。次の関数で初期化しておく必要があります: uv_udp_init()。
bufs – 送信するバッファのリストです。
nbufs – 次のリスト内のバッファ数です: bufs。
addr – struct sockaddr_inまたはstruct sockaddr_in6型の、リモートピアのアドレスとポートを格納した構造体です。
send_cb – データの送信後に呼び出すコールバックです。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

バージョン1.19.0での変更: 次のアドレス、0.0.0.0と::をlocalhostへ対応付ける処理を追加しました。

バージョン1.27.0での変更: 接続済みソケットのサポートを追加しました。

int uv_udp_try_send(uv_udp_t *handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr *addr)¶

次の関数、uv_udp_send()と同じですが、即座に完了できない場合も送信要求をキューに入れません。

接続済みのUDPハンドルでは、addrをNULLに設定してください。それ以外はUV_EISCONNエラーを返します。

未接続のUDPハンドルでは、addrをNULLにできません。そうするとUV_EDESTADDRREQエラーを返します。

戻り値:: 0以上: 送信したバイト数（指定したバッファサイズと一致します）。0未満: 負のエラーコード（即座に送信できない場合は、UV_EAGAINを返します）。

バージョン1.27.0での変更: 接続済みソケットのサポートを追加しました。

int uv_udp_try_send2(uv_udp_t *handle, unsigned int count, uv_buf_t *bufs[/*count*/], unsigned int nbufs[/*count*/], struct sockaddr *addrs[/*count*/], unsigned int flags)¶

次の関数、uv_udp_try_send()と同様ですが、複数のデータグラムを送信できます。次の関数を簡潔に抽象化しています: sendmmsg(2)。この関数をサポートしないプラットフォームでは、sendmsg(2)を使うループへフォールバックします。ハンドルは完全に初期化する必要があります。先にc:func:uv_udp_bindを呼び出してください。

戻り値:: 0以上: 送信したデータグラム数。0になるのは、countが0だった場合だけです。0未満: 負のエラーコード。最初のデータグラムの送信に失敗した場合だけ負の値となり、それ以外は正の送信数を返します。即座に送信できないときは、UV_EAGAINになります。次の関数へフォールバックしてください: uv_udp_send()。

バージョン1.50.0で追加。

int uv_udp_recv_start(uv_udp_t *handle, uv_alloc_cb alloc_cb, uv_udp_recv_cb recv_cb)¶

データの受信を準備します。ソケットを事前に次の関数、uv_udp_bind()でバインドしていなければ、0.0.0.0（すべてのインターフェイスを表すIPv4アドレス）とランダムなポート番号へバインドします。

パラメーター:

handle – UDPハンドルです。次の関数で初期化しておく必要があります: uv_udp_init()。
alloc_cb – 一時記憶領域が必要なときに呼び出すコールバックです。
recv_cb – 受信したデータを渡して呼び出すコールバックです。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

注記

次の関数、recvmmsg(2)を使う場合、1回に受信するメッセージ数の上限は、alloc_cbが確保したバッファに収まる最大サイズのデータグラム数です。また、udp_recv用のsuggested_sizeは、alloc_cbで常に最大サイズのデータグラム1個分のサイズに設定されます。

バージョン1.35.0での変更: 対応プラットフォームでrecvmmsg(2)のサポートを追加しました。このハンドルのuv_alloc_cbは、64 KiBの倍数のバッファを作成してください。

バージョン1.37.0での変更: recvmmsg(2)のサポートは暗黙には有効にならなくなりました。次のフラグ、UV_UDP_RECVMMSGを、次の関数へ渡して明示的に要求してください: uv_udp_init_ex()。

バージョン1.39.0での変更: uv_udp_using_recvmmsg()をalloc_cb内で使い、現在のハンドルとプラットフォームでrecvmmsg(2)向けサイズのバッファを確保すべきか判断できます。

int uv_udp_using_recvmmsg(uv_udp_t *handle)¶: UDPハンドルを次のフラグ、UV_UDP_RECVMMSG付きで作成し、プラットフォームがrecvmmsg(2)をサポートしていれば1、それ以外は0を返します。

バージョン1.39.0で追加。

int uv_udp_recv_stop(uv_udp_t *handle)¶

受信データグラムの監視を停止します。

パラメーター:

handle – UDPハンドルです。次の関数で初期化しておく必要があります: uv_udp_init()。

戻り値:

成功時は0、失敗時は0未満のエラーコードを返します。

size_t uv_udp_get_send_queue_size(const uv_udp_t *handle)¶: 次の値を返します: handle->send_queue_size。

バージョン1.19.0で追加。

size_t uv_udp_get_send_queue_count(const uv_udp_t *handle)¶: 次の値を返します: handle->send_queue_count。

バージョン1.19.0で追加。

uv_udp_t — UDPハンドル¶

データ型¶

公開メンバー¶

API¶

`uv_udp_t` — UDPハンドル¶