WSAHtonl

関数

32ビット値をホスト順からネットワークバイト順へ変換する。

DLLWS2_32.dll呼出規約winapiSetLastErrorあり対応OSWindows 8.1 以降

シグネチャ

// WS2_32.dll
#include <windows.h>

INT WSAHtonl(
    SOCKET s,
    DWORD hostlong,
    DWORD* lpnetlong
);

パラメーター

名前	型	方向	説明
s	SOCKET	in	ソケットを識別するディスクリプタです。
hostlong	DWORD	in	ホストバイトオーダーの 32 ビットの数値です。
lpnetlong	DWORD*	out	ネットワークバイトオーダーの数値を受け取る 32 ビットの数値へのポインタです。

戻り値の型: INT

公式ドキュメント

WSAHtonl 関数は、u_long の値をホストバイトオーダーからネットワークバイトオーダーに変換します。

戻り値

エラーが発生しなかった場合、 WSAHtonl は 0 を返します。それ以外の場合は SOCKET_ERROR が返され、 WSAGetLastError を呼び出すことで具体的なエラーコードを取得できます。

エラーコード	意味
WSANOTINITIALISED	この関数を使用する前に、 WSAStartup の呼び出しが成功している必要があります。
WSAENETDOWN	ネットワークサブシステムに障害が発生しました。
WSAENOTSOCK	ディスクリプタがソケットではありません。
WSAEFAULT	lpnetlong パラメーターが NULL であるか、指し示すアドレスがユーザーアドレス空間の有効な範囲内に完全に含まれていません。

解説(Remarks)

WSAHtonl 関数は、ホストバイトオーダーの 32 ビットの数値を受け取り、ネットワークバイトオーダーの 32 ビットの数値を lpnetlong パラメーターが指す 32 ビットの数値に返します。s パラメーターで渡されたソケットは、そのソケットに関連付けられた Winsock カタログのプロトコルエントリに基づいて、必要なネットワークバイトオーダーを判別するために使用されます。この機能により、異なるネットワークバイトオーダーを使用する Winsock プロバイダーがサポートされます。

ソケットが AF_INET または AF_INET6 アドレスファミリのものである場合、 WSAHtonl 関数を使用して、ホストバイトオーダーの IPv4 アドレスをネットワークバイトオーダーの IPv4 アドレスに変換できます。この関数は、hostlong パラメーターが有効な IPv4 アドレスであるかどうかのチェックは一切行いません。

WSAHtonl 関数を使用するには、事前に WSAStartup 関数の呼び出しが成功し、Winsock DLL が読み込まれている必要があります。AF_INET または AF_INET6 ファミリで使用する場合、htonl 関数は Winsock DLL の読み込みを必要としません。

Windows Phone 8: この関数は、Windows Phone 8 以降の Windows Phone ストアアプリでサポートされます。

Windows 8.1 および Windows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// WS2_32.dll
#include <windows.h>

INT WSAHtonl(
    SOCKET s,
    DWORD hostlong,
    DWORD* lpnetlong
);

[DllImport("WS2_32.dll", SetLastError = true, ExactSpelling = true)]
static extern int WSAHtonl(
    UIntPtr s,   // SOCKET
    uint hostlong,   // DWORD
    out uint lpnetlong   // DWORD* out
);

<DllImport("WS2_32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function WSAHtonl(
    s As UIntPtr,   ' SOCKET
    hostlong As UInteger,   ' DWORD
    <Out> ByRef lpnetlong As UInteger   ' DWORD* out
) As Integer
End Function

' s : SOCKET
' hostlong : DWORD
' lpnetlong : DWORD* out
Declare PtrSafe Function WSAHtonl Lib "ws2_32" ( _
    ByVal s As LongPtr, _
    ByVal hostlong As Long, _
    ByRef lpnetlong As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WSAHtonl = ctypes.windll.ws2_32.WSAHtonl
WSAHtonl.restype = ctypes.c_int
WSAHtonl.argtypes = [
    ctypes.c_size_t,  # s : SOCKET
    wintypes.DWORD,  # hostlong : DWORD
    ctypes.POINTER(wintypes.DWORD),  # lpnetlong : DWORD* out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WS2_32.dll')
WSAHtonl = Fiddle::Function.new(
  lib['WSAHtonl'],
  [
    Fiddle::TYPE_UINTPTR_T,  # s : SOCKET
    -Fiddle::TYPE_INT,  # hostlong : DWORD
    Fiddle::TYPE_VOIDP,  # lpnetlong : DWORD* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ws2_32")]
extern "system" {
    fn WSAHtonl(
        s: usize,  // SOCKET
        hostlong: u32,  // DWORD
        lpnetlong: *mut u32  // DWORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WS2_32.dll", SetLastError = true)]
public static extern int WSAHtonl(UIntPtr s, uint hostlong, out uint lpnetlong);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WS2_32_WSAHtonl' -Namespace Win32 -PassThru
# $api::WSAHtonl(s, hostlong, lpnetlong)

#uselib "WS2_32.dll"
#func global WSAHtonl "WSAHtonl" sptr, sptr, sptr
; WSAHtonl s, hostlong, varptr(lpnetlong)   ; 戻り値は stat
; s : SOCKET -> "sptr"
; hostlong : DWORD -> "sptr"
; lpnetlong : DWORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WS2_32.dll"
#cfunc global WSAHtonl "WSAHtonl" sptr, int, var
; res = WSAHtonl(s, hostlong, lpnetlong)
; s : SOCKET -> "sptr"
; hostlong : DWORD -> "int"
; lpnetlong : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WS2_32.dll"
#cfunc global WSAHtonl "WSAHtonl" sptr, int, sptr
; res = WSAHtonl(s, hostlong, varptr(lpnetlong))
; s : SOCKET -> "sptr"
; hostlong : DWORD -> "int"
; lpnetlong : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。