ホーム › Networking.WinSock › WSCWriteProviderOrder

WSCWriteProviderOrder

関数

Winsockトランスポートプロバイダーのカタログ順序を書き込む。

DLLWS2_32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

INT WSCWriteProviderOrder(
    DWORD* lpwdCatalogEntryId,
    DWORD dwNumberOfEntries
);

パラメーター

名前	型	方向	説明
lpwdCatalogEntryId	DWORD*	inout	WSAPROTOCOL_INFO 構造体に含まれる CatalogEntryId 要素の配列へのポインターです。CatalogEntryId 要素の順序が、プロトコルの新しい優先順位となります。
dwNumberOfEntries	DWORD	in	lpwdCatalogEntryId 配列内の要素数です。

戻り値の型: INT

公式ドキュメント

利用可能なトランスポートプロバイダーの順序を変更するために使用します。

戻り値

ルーチンが成功した場合、この関数は ERROR_SUCCESS(ゼロ)を返します。それ以外の場合は、特定のエラーコードを返します。

Error code	Meaning
WSAEINVAL	1 つ以上の引数が無効です。処理は行われませんでした。
WSANO_RECOVERY	回復不能なエラーが発生しました。このエラーは、次のような複数の状況で返されます。すなわち、Winsock レジストリへの書き込みに必要な管理者権限がユーザーに不足している場合や、カタログエントリのオープンまたは書き込み時に障害が発生した場合などです。
WSA_NOT_ENOUGH_MEMORY	使用可能なメモリが不足しています。このエラーは、新しいカタログエントリを割り当てるのに十分なメモリがない場合に返されます。
(other)	このルーチンは、任意のレジストリエラーコードを返すことがあります。

解説(Remarks)

トランスポートサービスプロバイダーが最初にインストールされた順序によって、サービスプロバイダーインターフェイスでの WSCEnumProtocols を通じた列挙順、またはアプリケーションインターフェイスでの WSAEnumProtocols を通じた列挙順が決定されます。さらに重要な点として、この順序は、クライアントがアドレスファミリ、タイプ、およびプロトコル識別子に基づいて socket の作成を要求したときに、どのプロトコルおよびサービスプロバイダーが検討されるかの順序も決定します。

Windows Sockets 2 には、プロトコルが既にインストールされた後で、インストール済みプロトコルのカタログを対話的に並べ替えできる Sporder.exe というアプリケーションが含まれています。また Windows Sockets 2 には、プロトコルを並べ替えるためのこの手続き型インターフェイスをエクスポートする補助 DLL である Sporder.dll も含まれています。このインターフェイスは Sporder.lib とリンクすることでインポートできます。

以下は、 WSCWriteProviderOrder 関数が失敗する可能性のあるシナリオです。

dwNumberOfEntries パラメーターが、登録されているサービスプロバイダーの数と一致しない場合。
lpwdCatalogEntryId に無効なカタログ識別子が含まれている場合。
lpwdCatalogEntryId が、すべての有効なカタログ識別子をちょうど 1 回ずつ含んでいない場合。
何らかの理由(たとえば、ユーザー権限の不足など)でルーチンがレジストリにアクセスできない場合。
別のプロセス(またはスレッド)が現在この関数を呼び出している場合。

成功した場合、WSCWriteProviderOrder は、WSAProviderConfigChange を呼び出して、変更の通知を登録しているすべての関係アプリケーションに通知を試みます。

WSCWriteProviderOrder 関数は、Administrators グループのメンバーとしてログオンしているユーザーのみが呼び出すことができます。WSCWriteProviderOrder が Administrators グループのメンバーでないユーザーによって呼び出された場合、関数呼び出しは失敗し、 WSANO_RECOVERY が返されます。 Windows Vista または Windows Server 2008 上で動作するコンピューターでは、ユーザーアカウント制御(UAC)が原因でこの関数が失敗することもあります。この関数を含むアプリケーションが、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーによって実行された場合、マニフェストファイルでアプリケーションの requestedExecutionLevel が requireAdministrator に設定されていない限り、この呼び出しは失敗します。Windows Vista または Windows Server 2008 上のアプリケーションにこのマニフェストファイルがない場合、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーは、この関数を成功させるために、組み込みの Administrator として拡張シェル(RunAs administrator)でアプリケーションを実行する必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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 WSCWriteProviderOrder(
    DWORD* lpwdCatalogEntryId,
    DWORD dwNumberOfEntries
);

[DllImport("WS2_32.dll", ExactSpelling = true)]
static extern int WSCWriteProviderOrder(
    ref uint lpwdCatalogEntryId,   // DWORD* in/out
    uint dwNumberOfEntries   // DWORD
);

<DllImport("WS2_32.dll", ExactSpelling:=True)>
Public Shared Function WSCWriteProviderOrder(
    ByRef lpwdCatalogEntryId As UInteger,   ' DWORD* in/out
    dwNumberOfEntries As UInteger   ' DWORD
) As Integer
End Function

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

import ctypes
from ctypes import wintypes

WSCWriteProviderOrder = ctypes.windll.ws2_32.WSCWriteProviderOrder
WSCWriteProviderOrder.restype = ctypes.c_int
WSCWriteProviderOrder.argtypes = [
    ctypes.POINTER(wintypes.DWORD),  # lpwdCatalogEntryId : DWORD* in/out
    wintypes.DWORD,  # dwNumberOfEntries : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WS2_32.dll')
WSCWriteProviderOrder = Fiddle::Function.new(
  lib['WSCWriteProviderOrder'],
  [
    Fiddle::TYPE_VOIDP,  # lpwdCatalogEntryId : DWORD* in/out
    -Fiddle::TYPE_INT,  # dwNumberOfEntries : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "ws2_32")]
extern "system" {
    fn WSCWriteProviderOrder(
        lpwdCatalogEntryId: *mut u32,  // DWORD* in/out
        dwNumberOfEntries: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WS2_32.dll")]
public static extern int WSCWriteProviderOrder(ref uint lpwdCatalogEntryId, uint dwNumberOfEntries);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WS2_32_WSCWriteProviderOrder' -Namespace Win32 -PassThru
# $api::WSCWriteProviderOrder(lpwdCatalogEntryId, dwNumberOfEntries)

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

出力引数:

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