FaxGetRoutingInfoW

関数

指定したルーティング方法の構成データを取得する。

DLLWINFAX.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

// WINFAX.dll  (Unicode / -W)
#include <windows.h>

BOOL FaxGetRoutingInfoW(
    HANDLE FaxPortHandle,
    LPCWSTR RoutingGuid,
    BYTE** RoutingInfoBuffer,
    DWORD* RoutingInfoBufferSize
);

パラメーター

名前	型	方向	説明
FaxPortHandle	HANDLE	in	FaxOpenPort 関数の呼び出しによって返された FAX ポートハンドルを指定します。
RoutingGuid	LPCWSTR	in	対象となる FAX ルーティング方法を一意に識別する GUID を指定する、定数の null 終端文字列へのポインターです。 FAX ルーティング方法については、About the Fax Routing Extension API を参照してください。ルーティング方法と GUID の関係については、Fax Routing Methods を参照してください。
RoutingInfoBuffer	BYTE**	out	FAX ルーティング情報を受け取るバッファーのアドレスへのポインターです。
RoutingInfoBufferSize	DWORD*	out	RoutingInfoBuffer パラメーターが指すバッファーのサイズ (バイト単位) を受け取る DWORD 変数へのポインターです。

戻り値の型: BOOL

公式ドキュメント

FaxGetRoutingInfo 関数は、特定の FAX デバイスに関連付けられた FAX ルーティング方法のルーティング情報を、FAX クライアントアプリケーションに返します。(Unicode)

戻り値

型: BOOL

関数が成功した場合、戻り値は 0 以外の値です。

関数が失敗した場合、戻り値は 0 です。拡張エラー情報を取得するには、GetLastError を呼び出します。GetLastError は次のいずれかのエラーを返すことがあります。

戻り値	説明
ERROR_ACCESS_DENIED	アクセスが拒否されました。FAX_PORT_QUERY アクセス権が必要です。
ERROR_INVALID_PARAMETER	RoutingGuid、RoutingInfoBuffer、RoutingInfoBufferSize、FaxPortHandle の各パラメーターのいずれか、またはすべてが NULL です。
ERROR_NOT_ENOUGH_MEMORY	メモリの割り当て中にエラーが発生しました。
ERROR_INVALID_DATA	RoutingGuid パラメーターが無効です。

解説(Remarks)

FaxGetRoutingInfo 関数は通常、指定された FAX ルーティング方法を管理する Microsoft 管理コンソール (MMC) スナップインコンポーネントである FAX サービス管理アプリケーションから呼び出されます。これは、ルーティングデータの形式が FAX クライアントアプリケーションからは利用できないためです。ルーティングデータは、エクスポートされた FAX ルーティング方法と FAX サービス管理アプリケーションにのみ関係します。

特定の FAX ルーティング方法を管理するアプリケーションは、FaxGetRoutingInfo 関数を呼び出して、指定した FAX デバイス上のその方法のルーティング情報を変更できます。デバイスに関連付けられているすべての FAX ルーティング方法を列挙するには、FaxEnumRoutingMethods 関数を呼び出します。

FaxEnumGlobalRoutingInfo 関数は、ルーティングの優先順位など、FAX サーバー全体に適用されるルーティング情報を取得します。アプリケーションは、FaxSetGlobalRoutingInfo 関数を呼び出すことで、グローバルデータを変更できます。

FaxGetRoutingInfo 関数は、RoutingInfoBuffer パラメーターが指すバッファーに必要なメモリを割り当てます。アプリケーションは、FaxFreeBuffer 関数を呼び出して、このパラメーターに関連付けられたリソースを解放する必要があります。

詳細については、Managing Fax Routing Data および Freeing Fax Resources を参照してください。

メモ

winfax.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして FaxGetRoutingInfo を定義しています。エンコーディングに依存しないエイリアスの使用と、エンコーディングに依存するコードを混在させると、不一致が生じてコンパイルエラーや実行時エラーの原因となる可能性があります。詳細については、Conventions for Function Prototypes を参照してください。

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

各言語での呼び出し定義

// WINFAX.dll  (Unicode / -W)
#include <windows.h>

BOOL FaxGetRoutingInfoW(
    HANDLE FaxPortHandle,
    LPCWSTR RoutingGuid,
    BYTE** RoutingInfoBuffer,
    DWORD* RoutingInfoBufferSize
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("WINFAX.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern bool FaxGetRoutingInfoW(
    IntPtr FaxPortHandle,   // HANDLE
    [MarshalAs(UnmanagedType.LPWStr)] string RoutingGuid,   // LPCWSTR
    IntPtr RoutingInfoBuffer,   // BYTE** out
    out uint RoutingInfoBufferSize   // DWORD* out
);

<DllImport("WINFAX.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function FaxGetRoutingInfoW(
    FaxPortHandle As IntPtr,   ' HANDLE
    <MarshalAs(UnmanagedType.LPWStr)> RoutingGuid As String,   ' LPCWSTR
    RoutingInfoBuffer As IntPtr,   ' BYTE** out
    <Out> ByRef RoutingInfoBufferSize As UInteger   ' DWORD* out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' FaxPortHandle : HANDLE
' RoutingGuid : LPCWSTR
' RoutingInfoBuffer : BYTE** out
' RoutingInfoBufferSize : DWORD* out
Declare PtrSafe Function FaxGetRoutingInfoW Lib "winfax" ( _
    ByVal FaxPortHandle As LongPtr, _
    ByVal RoutingGuid As LongPtr, _
    ByVal RoutingInfoBuffer As LongPtr, _
    ByRef RoutingInfoBufferSize As Long) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

FaxGetRoutingInfoW = ctypes.windll.winfax.FaxGetRoutingInfoW
FaxGetRoutingInfoW.restype = wintypes.BOOL
FaxGetRoutingInfoW.argtypes = [
    wintypes.HANDLE,  # FaxPortHandle : HANDLE
    wintypes.LPCWSTR,  # RoutingGuid : LPCWSTR
    ctypes.c_void_p,  # RoutingInfoBuffer : BYTE** out
    ctypes.POINTER(wintypes.DWORD),  # RoutingInfoBufferSize : DWORD* out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WINFAX.dll')
FaxGetRoutingInfoW = Fiddle::Function.new(
  lib['FaxGetRoutingInfoW'],
  [
    Fiddle::TYPE_VOIDP,  # FaxPortHandle : HANDLE
    Fiddle::TYPE_VOIDP,  # RoutingGuid : LPCWSTR
    Fiddle::TYPE_VOIDP,  # RoutingInfoBuffer : BYTE** out
    Fiddle::TYPE_VOIDP,  # RoutingInfoBufferSize : DWORD* out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "winfax")]
extern "system" {
    fn FaxGetRoutingInfoW(
        FaxPortHandle: *mut core::ffi::c_void,  // HANDLE
        RoutingGuid: *const u16,  // LPCWSTR
        RoutingInfoBuffer: *mut *mut u8,  // BYTE** out
        RoutingInfoBufferSize: *mut u32  // DWORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("WINFAX.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern bool FaxGetRoutingInfoW(IntPtr FaxPortHandle, [MarshalAs(UnmanagedType.LPWStr)] string RoutingGuid, IntPtr RoutingInfoBuffer, out uint RoutingInfoBufferSize);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WINFAX_FaxGetRoutingInfoW' -Namespace Win32 -PassThru
# $api::FaxGetRoutingInfoW(FaxPortHandle, RoutingGuid, RoutingInfoBuffer, RoutingInfoBufferSize)

#uselib "WINFAX.dll"
#func global FaxGetRoutingInfoW "FaxGetRoutingInfoW" wptr, wptr, wptr, wptr
; FaxGetRoutingInfoW FaxPortHandle, RoutingGuid, varptr(RoutingInfoBuffer), varptr(RoutingInfoBufferSize)   ; 戻り値は stat
; FaxPortHandle : HANDLE -> "wptr"
; RoutingGuid : LPCWSTR -> "wptr"
; RoutingInfoBuffer : BYTE** out -> "wptr"
; RoutingInfoBufferSize : DWORD* out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WINFAX.dll"
#cfunc global FaxGetRoutingInfoW "FaxGetRoutingInfoW" sptr, wstr, var, var
; res = FaxGetRoutingInfoW(FaxPortHandle, RoutingGuid, RoutingInfoBuffer, RoutingInfoBufferSize)
; FaxPortHandle : HANDLE -> "sptr"
; RoutingGuid : LPCWSTR -> "wstr"
; RoutingInfoBuffer : BYTE** out -> "var"
; RoutingInfoBufferSize : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WINFAX.dll"
#cfunc global FaxGetRoutingInfoW "FaxGetRoutingInfoW" sptr, wstr, sptr, sptr
; res = FaxGetRoutingInfoW(FaxPortHandle, RoutingGuid, varptr(RoutingInfoBuffer), varptr(RoutingInfoBufferSize))
; FaxPortHandle : HANDLE -> "sptr"
; RoutingGuid : LPCWSTR -> "wstr"
; RoutingInfoBuffer : BYTE** out -> "sptr"
; RoutingInfoBufferSize : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。