FaxStartPrintJobA

関数

ファクスプリンターへの印刷ジョブを開始しデバイスコンテキストを取得する。

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

シグネチャ

// WINFAX.dll  (ANSI / -A)
#include <windows.h>

BOOL FaxStartPrintJobA(
    LPCSTR PrinterName,
    const FAX_PRINT_INFOA* PrintInfo,
    DWORD* FaxJobId,
    FAX_CONTEXT_INFOA* FaxContextInfo
);

パラメーター

名前	型	方向	説明
PrinterName	LPCSTR	in	ファクスプリンターの名前を格納した、定数の null 終端文字列へのポインターです。この文字列には次のいずれかを指定できます。ローカルプリンター (例: "printername") ネットワークプリンター (例: "\\machinename\printername") ローカルのファクスプリンターを指定する場合は NULL
PrintInfo	FAX_PRINT_INFOA*	in	ファクスサーバーがファクス送信を印刷するために必要な情報を格納した FAX_PRINT_INFO 構造体へのポインターです。この構造体には、受信者のファクス番号、送信者と受信者のデータ、省略可能な課金コード、配信レポート情報などが含まれます。詳細については、以下の「解説」セクションを参照してください。
FaxJobId	DWORD*	out	ファクス印刷ジョブに対する印刷スプーラーの一意の ID を受け取る DWORD 変数へのポインターです。(これはファクスキューにおけるそのジョブの ID とは異なり、ファクス ID を受け取るファクス API のパラメーターとして使用することはできません。) このパラメーターは必須です。
FaxContextInfo	FAX_CONTEXT_INFOA*	out	プリンターのデバイスコンテキストへのハンドルを受け取る FAX_CONTEXT_INFO 構造体へのポインターです。ファクスクライアントアプリケーションは、FaxPrintCoverPage 関数を呼び出すときに、この値をその関数の FaxContextInfo パラメーターに渡す必要があります。詳細については、デバイスコンテキストおよび印刷と印刷スプーラーのリファレンスを参照してください。

戻り値の型: BOOL

公式ドキュメント

ファクスクライアントアプリケーションは、FaxStartPrintJob 関数を呼び出して、指定したファクスプリンターで送信ファクスの印刷を開始します。(ANSI)

戻り値

種類: BOOL

関数が成功した場合は、0 以外の値を返します。

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

戻り値	説明
ERROR_INVALID_PARAMETER	PrintInfo パラメーターまたは FaxContextInfo パラメーターのいずれか、あるいは両方が NULL です。
ERROR_INVALID_PARAMETER	FAX_PRINT_INFO 構造体の RecipientNumber メンバーが NULL であるか、OutputFileName メンバーが NULL で、かつ RecipientNumber メンバーが指定されていません。
ERROR_INVALID_PRINTER_NAME	PrinterName パラメーターで指定されたプリンターがファクスプリンターではないか、ファクスプリンターがインストールされていません。
ERROR_NOT_ENOUGH_MEMORY	メモリの割り当て中にエラーが発生しました。
ERROR_SPL_NO_STARTDOC	FaxStartPrintJob が先に呼び出されていないため、StartDoc の呼び出しが行われていません。

解説(Remarks)

この関数は、デバイスコンテキストへのハンドルを返します。このハンドルは、FaxPrintCoverPage 関数のほか、AbortDoc、EndDoc、DeleteDC、StartPage、EndPage などの Win32 Windows グラフィックスデバイスインターフェイス (GDI) 関数で使用されます。

注意アプリケーションは、印刷ジョブを完了するために AbortDoc 関数または EndDoc 関数も呼び出し、さらにプリンターのデバイスコンテキストへのハンドルを解放するために DeleteDC 関数を呼び出す必要があります。詳細については、ファクスをデバイスコンテキストに印刷するを参照してください。

ファクスクライアントアプリケーションは、ファクスプリンターのデバイスコンテキストを作成するために GDI の CreateDC 関数を呼び出してはならず、ファクス印刷ジョブを開始するために印刷関数の StartPage を呼び出してもいけません。代わりに、アプリケーションは FaxStartPrintJob 関数を呼び出す必要があります。これは、FaxStartPrintJob が対象のファクスプリンターに固有の DEVMODE 構造体の情報を変更するためです。

この変更により、ユーザーから情報を収集するファクス送信ウィザードが表示されなくなります。ファクスサーバーは、PrintInfo パラメーターが指す FAX_PRINT_INFO 構造体のデータを使用して、ファクス送信を印刷します。この構造体には、ファクス送信ウィザードが表示された場合にウィザードが収集していたはずのデータが格納されます。

ファクスクライアントアプリケーションは、ファクスジョブでカバーページを印刷するために FaxPrintCoverPage 関数を呼び出す前に、FaxStartPrintJob 関数を呼び出す必要があります。

メモ

winfax.h ヘッダーは、UNICODE プリプロセッサ定数の定義に応じて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして FaxStartPrintJob を定義します。エンコーディングに中立なこのエイリアスを、エンコーディングに中立でないコードと混在させて使用すると、不一致が生じてコンパイルエラーや実行時エラーの原因となる場合があります。詳細については、関数プロトタイプの規則を参照してください。

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

各言語での呼び出し定義

// WINFAX.dll  (ANSI / -A)
#include <windows.h>

BOOL FaxStartPrintJobA(
    LPCSTR PrinterName,
    const FAX_PRINT_INFOA* PrintInfo,
    DWORD* FaxJobId,
    FAX_CONTEXT_INFOA* FaxContextInfo
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("WINFAX.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern bool FaxStartPrintJobA(
    [MarshalAs(UnmanagedType.LPStr)] string PrinterName,   // LPCSTR
    IntPtr PrintInfo,   // FAX_PRINT_INFOA*
    out uint FaxJobId,   // DWORD* out
    IntPtr FaxContextInfo   // FAX_CONTEXT_INFOA* out
);

<DllImport("WINFAX.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function FaxStartPrintJobA(
    <MarshalAs(UnmanagedType.LPStr)> PrinterName As String,   ' LPCSTR
    PrintInfo As IntPtr,   ' FAX_PRINT_INFOA*
    <Out> ByRef FaxJobId As UInteger,   ' DWORD* out
    FaxContextInfo As IntPtr   ' FAX_CONTEXT_INFOA* out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' PrinterName : LPCSTR
' PrintInfo : FAX_PRINT_INFOA*
' FaxJobId : DWORD* out
' FaxContextInfo : FAX_CONTEXT_INFOA* out
Declare PtrSafe Function FaxStartPrintJobA Lib "winfax" ( _
    ByVal PrinterName As String, _
    ByVal PrintInfo As LongPtr, _
    ByRef FaxJobId As Long, _
    ByVal FaxContextInfo As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

FaxStartPrintJobA = ctypes.windll.winfax.FaxStartPrintJobA
FaxStartPrintJobA.restype = wintypes.BOOL
FaxStartPrintJobA.argtypes = [
    wintypes.LPCSTR,  # PrinterName : LPCSTR
    ctypes.c_void_p,  # PrintInfo : FAX_PRINT_INFOA*
    ctypes.POINTER(wintypes.DWORD),  # FaxJobId : DWORD* out
    ctypes.c_void_p,  # FaxContextInfo : FAX_CONTEXT_INFOA* out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WINFAX.dll')
FaxStartPrintJobA = Fiddle::Function.new(
  lib['FaxStartPrintJobA'],
  [
    Fiddle::TYPE_VOIDP,  # PrinterName : LPCSTR
    Fiddle::TYPE_VOIDP,  # PrintInfo : FAX_PRINT_INFOA*
    Fiddle::TYPE_VOIDP,  # FaxJobId : DWORD* out
    Fiddle::TYPE_VOIDP,  # FaxContextInfo : FAX_CONTEXT_INFOA* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "winfax")]
extern "system" {
    fn FaxStartPrintJobA(
        PrinterName: *const u8,  // LPCSTR
        PrintInfo: *const FAX_PRINT_INFOA,  // FAX_PRINT_INFOA*
        FaxJobId: *mut u32,  // DWORD* out
        FaxContextInfo: *mut FAX_CONTEXT_INFOA  // FAX_CONTEXT_INFOA* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("WINFAX.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern bool FaxStartPrintJobA([MarshalAs(UnmanagedType.LPStr)] string PrinterName, IntPtr PrintInfo, out uint FaxJobId, IntPtr FaxContextInfo);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WINFAX_FaxStartPrintJobA' -Namespace Win32 -PassThru
# $api::FaxStartPrintJobA(PrinterName, PrintInfo, FaxJobId, FaxContextInfo)

#uselib "WINFAX.dll"
#func global FaxStartPrintJobA "FaxStartPrintJobA" sptr, sptr, sptr, sptr
; FaxStartPrintJobA PrinterName, varptr(PrintInfo), varptr(FaxJobId), varptr(FaxContextInfo)   ; 戻り値は stat
; PrinterName : LPCSTR -> "sptr"
; PrintInfo : FAX_PRINT_INFOA* -> "sptr"
; FaxJobId : DWORD* out -> "sptr"
; FaxContextInfo : FAX_CONTEXT_INFOA* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WINFAX.dll"
#cfunc global FaxStartPrintJobA "FaxStartPrintJobA" str, var, var, var
; res = FaxStartPrintJobA(PrinterName, PrintInfo, FaxJobId, FaxContextInfo)
; PrinterName : LPCSTR -> "str"
; PrintInfo : FAX_PRINT_INFOA* -> "var"
; FaxJobId : DWORD* out -> "var"
; FaxContextInfo : FAX_CONTEXT_INFOA* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WINFAX.dll"
#cfunc global FaxStartPrintJobA "FaxStartPrintJobA" str, sptr, sptr, sptr
; res = FaxStartPrintJobA(PrinterName, varptr(PrintInfo), varptr(FaxJobId), varptr(FaxContextInfo))
; PrinterName : LPCSTR -> "str"
; PrintInfo : FAX_PRINT_INFOA* -> "sptr"
; FaxJobId : DWORD* out -> "sptr"
; FaxContextInfo : FAX_CONTEXT_INFOA* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。