WSANtohl

関数

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

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

シグネチャ

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

INT WSANtohl(
    SOCKET s,
    DWORD netlong,
    DWORD* lphostlong
);

パラメーター

名前	型	方向	説明
s	SOCKET	in	socket を識別する記述子。
netlong	DWORD	in	ネットワークバイトオーダーの 32 ビットの数値。
lphostlong	DWORD*	out	ホストバイトオーダーの数値を受け取る 32 ビットの数値へのポインター。

戻り値の型: INT

公式ドキュメント

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

戻り値

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

エラーコード	意味
WSANOTINITIALISED	この関数を使用する前に、 WSAStartup の呼び出しが成功している必要があります。
WSAENETDOWN	ネットワークサブシステムが失敗しました。
WSAENOTSOCK	記述子が socket ではありません。
WSAEFAULT	lphostlong パラメーターが NULL であるか、指し示すアドレスがユーザーアドレス空間の有効な部分に完全には含まれていません。

解説(Remarks)

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

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

WSANtohl 関数を使用するには、事前に WSAStartup 関数の呼び出しが成功し、Winsock DLL が読み込まれている必要があります。AF_INET または AF_INET6 ファミリーで使用する場合、ntohl 関数は 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 WSANtohl(
    SOCKET s,
    DWORD netlong,
    DWORD* lphostlong
);

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

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

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

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

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

#[link(name = "ws2_32")]
extern "system" {
    fn WSANtohl(
        s: usize,  // SOCKET
        netlong: u32,  // DWORD
        lphostlong: *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 WSANtohl(UIntPtr s, uint netlong, out uint lphostlong);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WS2_32_WSANtohl' -Namespace Win32 -PassThru
# $api::WSANtohl(s, netlong, lphostlong)

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

出力引数:

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