ホーム › NetworkManagement.WiFi › WlanHostedNetworkSetProperty

WlanHostedNetworkSetProperty

関数

ホストネットワークの指定プロパティ値を設定する。

DLLwlanapi.dll呼出規約winapi対応OSWindows 7 以降

シグネチャ

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

DWORD WlanHostedNetworkSetProperty(
    HANDLE hClientHandle,
    WLAN_HOSTED_NETWORK_OPCODE OpCode,
    DWORD dwDataSize,
    void* pvData,
    WLAN_HOSTED_NETWORK_REASON* pFailReason,   // optional
    void* pvReserved   // optional
);

パラメーター

名前	型	方向	説明
hClientHandle	HANDLE	in	クライアントのセッションハンドル。事前に WlanOpenHandle 関数を呼び出して取得します。
OpCode	WLAN_HOSTED_NETWORK_OPCODE	in	設定するプロパティの識別子。この識別子には、Wlanapi.h ヘッダーファイルで定義されている WLAN_HOSTED_NETWORK_OPCODE 列挙型のうち、次の値のみを指定できます。 wlan_hosted_network_opcode_connection_settings Hosted Network の接続設定。 wlan_hosted_network_opcode_enable Hosted Network の有効化フラグ。
dwDataSize	DWORD	in	pvData パラメーターが指すバッファーのサイズ (バイト単位) を指定する値。
pvData	void*	in	設定する静的プロパティを格納したバッファーへのポインター。このバッファーに関連付けられるデータ型は、OpCode パラメーターの値によって異なります。
pFailReason	WLAN_HOSTED_NETWORK_REASON*	outoptional	WlanHostedNetworkSetProperty 関数の呼び出しが失敗した場合に、失敗の理由を受け取る値への省略可能なポインター。失敗の理由として指定され得る値は、Wlanapi.h ヘッダーファイルで定義されている WLAN_HOSTED_NETWORK_REASON 列挙型の値です。
pvReserved	void*	optional	将来の使用のために予約されています。このパラメーターは NULL でなければなりません。

戻り値の型: DWORD

公式ドキュメント

ワイヤレス Hosted Network の静的プロパティを設定します。

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値は次のいずれかのリターンコードになることがあります。

リターンコード	説明
ERROR_ACCESS_DENIED	呼び出し元に十分なアクセス許可がありません。このエラーは、OpCode パラメーターが wlan_hosted_network_opcode_enable であり、かつドメインのグループポリシーによってワイヤレス Hosted Network が無効にされている場合にも返されます。
ERROR_BAD_PROFILE	ワイヤレス Hosted Network が使用しているネットワーク接続プロファイルが破損しています。
ERROR_INVALID_HANDLE	ハンドルが無効です。このエラーは、hClientHandle パラメーターで指定されたハンドルがハンドルテーブル内に見つからなかった場合に返されます。
ERROR_INVALID_PARAMETER	パラメーターが正しくありません。このエラーは、次のいずれかの条件に該当する場合に返されます。 hClientHandle が NULL である。 OpCode が WLAN_HOSTED_NETWORK_OPCODE で定義された列挙値のいずれでもない。 dwDataSize が 0 である。 pvData が NULL である。 pvData が正しい形式の静的プロパティを指していない。 pvReserved が NULL ではない。
ERROR_INVALID_STATE	要求された操作を実行するのに適切な状態にリソースがありません。これは、ワイヤレス Hosted Network がシャットダウン処理中であった場合に発生することがあります。
ERROR_NOT_SUPPORTED	要求はサポートされていません。このエラーは、アプリケーションが OpCode パラメーターに wlan_hosted_network_opcode_station_profile または wlan_hosted_network_opcode_security_settings を設定して WlanHostedNetworkSetProperty 関数を呼び出した場合に返されます。
ERROR_SERVICE_NOT_ACTIVE	サービスが開始されていません。このエラーは、WLAN AutoConfig サービスが実行されていない場合に返されます。
その他	さまざまな RPC エラーおよびその他のエラーコード。返されたエラーに対応するメッセージ文字列を取得するには、 FormatMessage を使用してください。

解説(Remarks)

WlanHostedNetworkSetProperty 関数は、Windows 7 および Wireless LAN サービスがインストールされた Windows Server 2008 R2 でワイヤレス Hosted Network をサポートするために追加された、ネイティブワイヤレス API の拡張です。

クライアントアプリケーションは、ワイヤレス Hosted Network の現在の静的プロパティを設定するために WlanHostedNetworkSetProperty 関数を呼び出します。この関数によって生じた Hosted Network のプロパティ変更は、呼び出し元のアプリケーションが (hClientHandle パラメーターを指定して WlanCloseHandle を呼び出して) 呼び出しハンドルを閉じた場合やプロセスが終了した場合でも、自動的に元に戻されることはありません。

pvData パラメーターが指すバッファーに関連付けられるデータ型は、OpCode パラメーターの値に応じて次のようになります。

OpCode	説明
wlan_hosted_network_opcode_connection_settings	pvData パラメーターで WLAN_HOSTED_NETWORK_CONNECTION_SETTINGS 構造体へのポインターを渡します。
wlan_hosted_network_opcode_enable	pvData パラメーターで BOOL へのポインターを渡します。

WlanHostedNetworkSetProperty 関数を OpCode パラメーターに wlan_hosted_network_opcode_enable を設定して呼び出す場合、ユーザーは対応する適切な特権を持っている必要があります。アクセス許可は、WLAN_SECURABLE_OBJECT に関連付けられた随意アクセス制御リスト (DACL) に格納されます。 OpCode パラメーターに wlan_hosted_network_opcode_enable を指定して WlanHostedNetworkSetProperty 関数を呼び出すには、呼び出し元のクライアントアクセストークンが、WLAN_SECURABLE_OBJECT の次の列挙値によって公開される昇格された特権を持っている必要があります。

wlan_secure_hosted_network_elevated_access

WlanHostedNetworkSetProperty 関数の OpCode パラメーターに次のいずれかの値が渡された場合、この関数は ERROR_NOT_SUPPORTED で失敗します。

wlan_hosted_network_opcode_station_profile
wlan_hosted_network_opcode_connection_settings

WlanHostedNetworkSetProperty 関数が成功するには、新しい設定を永続化する必要があり、そのためには Hosted Network が実行中 (wlan_hosted_network_active) であった場合にその状態を wlan_hosted_network_idle へ遷移させる必要があります。

どのユーザーでもこの関数を呼び出して Hosted Network のプロパティを設定できます。ただし、wlan_hosted_network_opcode_enable フラグを設定するには昇格された特権が必要です。また、ワイヤレス Hosted Network を有効にできるかどうかは、ドメインのグループポリシーによって制限される場合もあります。

Windows 7 以降では、Hosted Network に対応したワイヤレスアダプターがコンピューターに存在する場合、オペレーティングシステムは仮想デバイスをインストールします。コンピューターにワイヤレスネットワークアダプターが 1 つだけある場合、この仮想デバイスは通常「ネットワーク接続フォルダー」に、デバイス名が「Microsoft Virtual WiFi Miniport adapter」の「ワイヤレスネットワーク接続 2」として表示されます。この仮想デバイスはソフトウェアアクセスポイント (SoftAP) 接続を行うためだけに使用され、WlanEnumInterfaces 関数が返す一覧には含まれません。この仮想デバイスの有効期間は物理ワイヤレスアダプターに連動します。物理ワイヤレスアダプターが無効にされると、この仮想デバイスも削除されます。この機能は、Wireless LAN サービスがインストールされた Windows Server 2008 R2 でも利用できます。

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

各言語での呼び出し定義

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

DWORD WlanHostedNetworkSetProperty(
    HANDLE hClientHandle,
    WLAN_HOSTED_NETWORK_OPCODE OpCode,
    DWORD dwDataSize,
    void* pvData,
    WLAN_HOSTED_NETWORK_REASON* pFailReason,   // optional
    void* pvReserved   // optional
);

[DllImport("wlanapi.dll", ExactSpelling = true)]
static extern uint WlanHostedNetworkSetProperty(
    IntPtr hClientHandle,   // HANDLE
    int OpCode,   // WLAN_HOSTED_NETWORK_OPCODE
    uint dwDataSize,   // DWORD
    IntPtr pvData,   // void*
    IntPtr pFailReason,   // WLAN_HOSTED_NETWORK_REASON* optional, out
    IntPtr pvReserved   // void* optional
);

<DllImport("wlanapi.dll", ExactSpelling:=True)>
Public Shared Function WlanHostedNetworkSetProperty(
    hClientHandle As IntPtr,   ' HANDLE
    OpCode As Integer,   ' WLAN_HOSTED_NETWORK_OPCODE
    dwDataSize As UInteger,   ' DWORD
    pvData As IntPtr,   ' void*
    pFailReason As IntPtr,   ' WLAN_HOSTED_NETWORK_REASON* optional, out
    pvReserved As IntPtr   ' void* optional
) As UInteger
End Function

' hClientHandle : HANDLE
' OpCode : WLAN_HOSTED_NETWORK_OPCODE
' dwDataSize : DWORD
' pvData : void*
' pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out
' pvReserved : void* optional
Declare PtrSafe Function WlanHostedNetworkSetProperty Lib "wlanapi" ( _
    ByVal hClientHandle As LongPtr, _
    ByVal OpCode As Long, _
    ByVal dwDataSize As Long, _
    ByVal pvData As LongPtr, _
    ByVal pFailReason As LongPtr, _
    ByVal pvReserved As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WlanHostedNetworkSetProperty = ctypes.windll.wlanapi.WlanHostedNetworkSetProperty
WlanHostedNetworkSetProperty.restype = wintypes.DWORD
WlanHostedNetworkSetProperty.argtypes = [
    wintypes.HANDLE,  # hClientHandle : HANDLE
    ctypes.c_int,  # OpCode : WLAN_HOSTED_NETWORK_OPCODE
    wintypes.DWORD,  # dwDataSize : DWORD
    ctypes.POINTER(None),  # pvData : void*
    ctypes.c_void_p,  # pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out
    ctypes.POINTER(None),  # pvReserved : void* optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('wlanapi.dll')
WlanHostedNetworkSetProperty = Fiddle::Function.new(
  lib['WlanHostedNetworkSetProperty'],
  [
    Fiddle::TYPE_VOIDP,  # hClientHandle : HANDLE
    Fiddle::TYPE_INT,  # OpCode : WLAN_HOSTED_NETWORK_OPCODE
    -Fiddle::TYPE_INT,  # dwDataSize : DWORD
    Fiddle::TYPE_VOIDP,  # pvData : void*
    Fiddle::TYPE_VOIDP,  # pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out
    Fiddle::TYPE_VOIDP,  # pvReserved : void* optional
  ],
  -Fiddle::TYPE_INT)

#[link(name = "wlanapi")]
extern "system" {
    fn WlanHostedNetworkSetProperty(
        hClientHandle: *mut core::ffi::c_void,  // HANDLE
        OpCode: i32,  // WLAN_HOSTED_NETWORK_OPCODE
        dwDataSize: u32,  // DWORD
        pvData: *mut (),  // void*
        pFailReason: *mut i32,  // WLAN_HOSTED_NETWORK_REASON* optional, out
        pvReserved: *mut ()  // void* optional
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("wlanapi.dll")]
public static extern uint WlanHostedNetworkSetProperty(IntPtr hClientHandle, int OpCode, uint dwDataSize, IntPtr pvData, IntPtr pFailReason, IntPtr pvReserved);
"@
$api = Add-Type -MemberDefinition $sig -Name 'wlanapi_WlanHostedNetworkSetProperty' -Namespace Win32 -PassThru
# $api::WlanHostedNetworkSetProperty(hClientHandle, OpCode, dwDataSize, pvData, pFailReason, pvReserved)

#uselib "wlanapi.dll"
#func global WlanHostedNetworkSetProperty "WlanHostedNetworkSetProperty" sptr, sptr, sptr, sptr, sptr, sptr
; WlanHostedNetworkSetProperty hClientHandle, OpCode, dwDataSize, pvData, varptr(pFailReason), pvReserved   ; 戻り値は stat
; hClientHandle : HANDLE -> "sptr"
; OpCode : WLAN_HOSTED_NETWORK_OPCODE -> "sptr"
; dwDataSize : DWORD -> "sptr"
; pvData : void* -> "sptr"
; pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out -> "sptr"
; pvReserved : void* optional -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "wlanapi.dll"
#cfunc global WlanHostedNetworkSetProperty "WlanHostedNetworkSetProperty" sptr, int, int, sptr, var, sptr
; res = WlanHostedNetworkSetProperty(hClientHandle, OpCode, dwDataSize, pvData, pFailReason, pvReserved)
; hClientHandle : HANDLE -> "sptr"
; OpCode : WLAN_HOSTED_NETWORK_OPCODE -> "int"
; dwDataSize : DWORD -> "int"
; pvData : void* -> "sptr"
; pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out -> "var"
; pvReserved : void* optional -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "wlanapi.dll"
#cfunc global WlanHostedNetworkSetProperty "WlanHostedNetworkSetProperty" sptr, int, int, sptr, sptr, sptr
; res = WlanHostedNetworkSetProperty(hClientHandle, OpCode, dwDataSize, pvData, varptr(pFailReason), pvReserved)
; hClientHandle : HANDLE -> "sptr"
; OpCode : WLAN_HOSTED_NETWORK_OPCODE -> "int"
; dwDataSize : DWORD -> "int"
; pvData : void* -> "sptr"
; pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out -> "sptr"
; pvReserved : void* optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。