ホーム › NetworkManagement.WiFi › WlanHostedNetworkForceStop

WlanHostedNetworkForceStop

関数

ホストネットワークを参照カウントに関係なく強制的に停止する。

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

シグネチャ

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

DWORD WlanHostedNetworkForceStop(
    HANDLE hClientHandle,
    WLAN_HOSTED_NETWORK_REASON* pFailReason,   // optional
    void* pvReserved   // optional
);

パラメーター

名前	型	方向	説明
hClientHandle	HANDLE	in	クライアントのセッションハンドル。WlanOpenHandle 関数の以前の呼び出しによって返された値です。
pFailReason	WLAN_HOSTED_NETWORK_REASON*	outoptional	WlanHostedNetworkForceStop 関数の呼び出しが失敗した場合に、その失敗理由を受け取る値への省略可能なポインター。失敗理由として指定される値は、Wlanapi.h ヘッダーファイルで定義されている WLAN_HOSTED_NETWORK_REASON 列挙型の値です。
pvReserved	void*	optional	将来の使用のために予約されています。このパラメーターは NULL でなければなりません。

戻り値の型: DWORD

公式ドキュメント

要求をアプリケーションの呼び出し元ハンドルに関連付けることなく、ワイヤレス Hosted Network を wlan_hosted_network_idle に遷移させます。

戻り値

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

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

リターンコード	説明
ERROR_INVALID_HANDLE	ハンドルが無効です。このエラーは、hClientHandle パラメーターで指定されたハンドルがハンドルテーブル内に見つからなかった場合に返されます。
ERROR_INVALID_PARAMETER	パラメーターが正しくありません。このエラーは、次のいずれかの条件に該当する場合に返されます。 hClientHandle が NULL である。 pvReserved が NULL ではない。
ERROR_INVALID_STATE	要求された操作を実行するための正しい状態にリソースがありません。
ERROR_SERVICE_NOT_ACTIVE	サービスが開始されていません。このエラーは、WLAN AutoConfig サービスが実行されていない場合に返されます。
その他	さまざまな RPC エラーやその他のエラーコード。返されたエラーのメッセージ文字列を取得するには、 FormatMessage を使用してください。

解説(Remarks)

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

クライアントアプリケーションは、Hosted Network を強制的に停止し、要求をアプリケーションの呼び出し元ハンドルに関連付けることなくワイヤレス Hosted Network を wlan_hosted_network_idle に遷移させるために、WlanHostedNetworkForceStop 関数を呼び出します。通常、クライアントは以前に成功した WlanHostedNetworkForceStart 関数の呼び出しに対応させるために WlanHostedNetworkForceStop 関数を呼び出します。

Hosted Network の状態が wlan_hosted_network_active でない場合、WlanHostedNetworkForceStop 関数は失敗することがあります。

この関数によって生じた Hosted Network の状態変化は、呼び出し元のアプリケーションが呼び出し元ハンドルを閉じても (hClientHandle パラメーターを指定して WlanCloseHandle を呼び出した場合)、またはプロセスが終了しても、自動的に元に戻されることはありません。

ワイヤレス Hosted Network を長時間実行することに伴う消費電力の増加を了承した昇格されたシステムユーザーが以前に WlanHostedNetworkForceStart を呼び出した後、アプリケーションが Hosted Network を停止するために WlanHostedNetworkForceStop 関数を呼び出すことがあります。

すべてのユーザーが WlanHostedNetworkForceStop 関数を呼び出して Hosted Network を強制的に停止できます。ただし、ドメイン環境では、ワイヤレス 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 WlanHostedNetworkForceStop(
    HANDLE hClientHandle,
    WLAN_HOSTED_NETWORK_REASON* pFailReason,   // optional
    void* pvReserved   // optional
);

[DllImport("wlanapi.dll", ExactSpelling = true)]
static extern uint WlanHostedNetworkForceStop(
    IntPtr hClientHandle,   // HANDLE
    IntPtr pFailReason,   // WLAN_HOSTED_NETWORK_REASON* optional, out
    IntPtr pvReserved   // void* optional
);

<DllImport("wlanapi.dll", ExactSpelling:=True)>
Public Shared Function WlanHostedNetworkForceStop(
    hClientHandle As IntPtr,   ' HANDLE
    pFailReason As IntPtr,   ' WLAN_HOSTED_NETWORK_REASON* optional, out
    pvReserved As IntPtr   ' void* optional
) As UInteger
End Function

' hClientHandle : HANDLE
' pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out
' pvReserved : void* optional
Declare PtrSafe Function WlanHostedNetworkForceStop Lib "wlanapi" ( _
    ByVal hClientHandle 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

WlanHostedNetworkForceStop = ctypes.windll.wlanapi.WlanHostedNetworkForceStop
WlanHostedNetworkForceStop.restype = wintypes.DWORD
WlanHostedNetworkForceStop.argtypes = [
    wintypes.HANDLE,  # hClientHandle : HANDLE
    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')
WlanHostedNetworkForceStop = Fiddle::Function.new(
  lib['WlanHostedNetworkForceStop'],
  [
    Fiddle::TYPE_VOIDP,  # hClientHandle : HANDLE
    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 WlanHostedNetworkForceStop(
        hClientHandle: *mut core::ffi::c_void,  // HANDLE
        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 WlanHostedNetworkForceStop(IntPtr hClientHandle, IntPtr pFailReason, IntPtr pvReserved);
"@
$api = Add-Type -MemberDefinition $sig -Name 'wlanapi_WlanHostedNetworkForceStop' -Namespace Win32 -PassThru
# $api::WlanHostedNetworkForceStop(hClientHandle, pFailReason, pvReserved)

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

出力引数:

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