SetPrinterDataEx 関数

  • [アーティクル]

SetPrinterDataEx 関数は、プリンターまたはプリント サーバーの構成データを設定します。 関数は、プリンターのレジストリ キーの下に構成データを格納します。

構文

DWORD SetPrinterDataEx(
  _In_ HANDLE  hPrinter,
  _In_ LPCTSTR pKeyName,
  _In_ LPCTSTR pValueName,
  _In_ DWORD   Type,
  _In_ LPBYTE  pData,
  _In_ DWORD   cbData
);

パラメーター

hPrinter [in]

関数が構成データを設定するプリンターまたはプリント サーバーへのハンドル。 プリンター ハンドルを取得するには、 OpenPrinter、 OpenPrinter2、または AddPrinter 関数を使用します。

pKeyName [in]

設定する値を含むキーを指定する null で終わる文字列へのポインター。 指定したキーまたはサブキーが存在しない場合、関数によって作成されます。

ディレクトリ サービス (DS) で発行できる構成データを格納するには、次の定義済みレジストリ キーのいずれかを指定します。

値 説明
SPLDS_DRIVER_KEY
 プリンター ドライバーは、このキーを使用してドライバーのプロパティを格納します。
SPLDS_SPOOLER_KEY
 予約済み。 内部スプーラー プロパティを格納するために印刷スプーラーによってのみ使用されます。
SPLDS_USER_KEY
 アプリケーションでは、このキーを使用して、プリンター資産番号などのプリンター プロパティを格納します。

SPLDS_USER_KEY キーの下に格納される値は、スキーマに対応するプロパティがある場合にのみ、ディレクトリ サービスに発行されます。 ドメイン管理者は、まだ存在しない場合は、プロパティを作成する必要があります。 SetPrinterDataEx を使用して値を追加または変更した後にユーザー定義プロパティを発行するには、Level = 7 の SetPrinter を呼び出し、PRINTER_INFO_7 dwAction メンバーを DSPRINT_UPDATEに設定します。

DS 以外の構成データを格納する他のキーを指定できます。 区切り記号として円記号 ( \ ) 文字を使用して、1 つ以上のサブキーを持つパスを指定します。

hPrinter がプリンターのハンドルで、pKeyName が NULL または空の文字列である場合、SetPrinterDataEx はERROR_INVALID_PARAMETERを返します。

hPrinter がプリント サーバーへのハンドルである場合、pKeyName は無視されます。

SPLDS_SPOOLER_KEYは使用しないでください。 スプーラー プリンターのプロパティを変更するには、Level = 2 の SetPrinter を使用します。

pValueName [in]

設定するデータを識別する null で終わる文字列へのポインター。

プリンターの場合、この文字列は pKeyName キーの値の名前を指定します。

プリント サーバーの場合、この文字列は、次の「解説」セクションに記載されている定義済みの文字列の 1 つです。

「in」と入力します

pData パラメーターによって指されるデータの種類を示すコード。 使用可能な型コードの一覧については、「 レジストリ値の型」を参照してください。

pKeyName で定義済みのディレクトリ サービス キーのいずれかを指定する場合、Type はREG_SZ、REG_MULTI_SZ、REG_DWORD、またはREG_BINARYである必要があります。 REG_BINARYを使用する場合、cbData は 1 に等しく、ディレクトリ サービスはデータをブール値として扱います。

pData [in]

プリンター構成データを含むバッファーへのポインター。

cbData [in]

配列のサイズ (バイト単位)。

戻り値

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

関数が失敗した場合、戻り値はエラー値です。

解説

注意

これはブロック関数または同期関数であり、すぐには返されない場合があります。 この関数が返す速度は、アプリケーションの作成時に予測が困難なネットワーク状態、プリント サーバーの構成、プリンター ドライバーの実装要因などの実行時の要因によって異なります。 ユーザー インターフェイスとの対話を管理するスレッドからこの関数を呼び出すと、アプリケーションが応答しなくなる可能性があります。

プリンターまたは印刷スプーラーの既存の構成データを取得するには、 GetPrinterDataEx 関数を呼び出します。

pKeyName パラメーターを "PrinterDriverData" に設定して SetPrinterDataEx を呼び出すことは、SetPrinterData 関数の呼び出しと同じです。

hPrinter がプリント サーバーへのハンドルである場合、pValueName は次の定義済みの値のいずれかを指定できます。

値 説明
SPLREG_ALLOW_USER_MANAGEFORMS Windows XP Service Pack 2 (SP2) 以降
Windows Server 2003 Service Pack 1 (SP1) 以降
SPLREG_BEEP_ENABLED
SPLREG_DEFAULT_SPOOL_DIRECTORY
SPLREG_EVENT_LOG
SPLREG_NET_POPUP Windows Server 2003 以降ではサポートされていません
SPLREG_PORT_THREAD_PRIORITY_DEFAULT
SPLREG_PORT_THREAD_PRIORITY
SPLREG_PRINT_DRIVER_ISOLATION_GROUPS Windows 7 以降
SPLREG_PRINT_DRIVER_ISOLATION_TIME_BEFORE_RECYCLE Windows 7 以降
SPLREG_PRINT_DRIVER_ISOLATION_MAX_OBJECTS_BEFORE_RECYCLE Windows 7 以降
SPLREG_PRINT_DRIVER_ISOLATION_IDLE_TIMEOUT Windows 7 以降
SPLREG_PRINT_DRIVER_ISOLATION_EXECUTION_POLICY Windows 7 以降
SPLREG_PRINT_DRIVER_ISOLATION_OVERRIDE_POLICY Windows 7 以降
SPLREG_RETRY_POPUP 正常に戻ると、サーバーがすべてのジョブのポップアップ ウィンドウを再試行するように設定されている場合は pData に 1、すべてのジョブに対してサーバーがポップアップ ウィンドウを再試行しない場合は 0 が含まれます。
Windows Server 2003 以降ではサポートされていません
SPLREG_SCHEDULER_THREAD_PRIORITY
SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT
SPLREG_WEBSHAREMGMT Windows Server 2003 以降

次の定義済みの値のいずれかを pValueName として渡すと、エラーが発生した場合のプールの印刷動作が設定されます。

値 説明
SPLREG_RESTART_JOB_ON_POOL_ERROR pData の値は、エラーが発生した後に別のポートでジョブが再起動された時刻 (秒単位) を示します。 この設定は 、SPLREG_RESTART_JOB_ON_POOL_ENABLEDで使用されます。
SPLREG_RESTART_JOB_ON_POOL_ENABLED pData の 0 以外の値は、SPLREG_RESTART_JOB_ON_POOL_ERRORが有効になっていることを示します。

SPLREG_RESTART_JOB_ON_POOL_ERRORで指定された時間は最小時間です。 実際の時間は、次のポート モニター設定 (このレジストリ キーの下のレジストリ値) に応じて、長くなる可能性があります。

HKLM\SYSTEM\CurrentControlSet\Control\Print\Monitors\<MonitorName>\Ports

これらの値を設定するには、 RegSetValueEx 関数を呼び出します。

ポート モニターの設定 データ型 説明
StatusUpdateEnabled REG_DWORD 0 以外の値の場合は、ポート モニターがポートの状態でスプーラーを更新できるようにします。
StatusUpdateInterval REG_DWORD ポート モニターがスプーラーをポートの状態で更新する間隔を分単位で指定します。

スプーラーがプール内の次に使用可能なプリンターにジョブをリダイレクトするには (設定時間内に印刷ジョブが印刷されない場合)、ポート モニターは SNMP をサポートする必要があり、プール内のネットワーク ポートは "SNMP 状態が有効" として構成されている必要があります。SNMP をサポートするポート モニターは、Standard TCP/IP ポート モニターです。

Windows 7 以降のバージョンの Windows では、プリント サーバーに送信される印刷ジョブは、既定でクライアントにレンダリングされます。 印刷ジョブのクライアント側レンダリングは、 pKeyName を "PrinterDriverData" に、 pValueName を次の表の設定値に設定することで構成できます。

設定 データ型 説明
EMFDespoolingSetting REG_DWORD 値が 0 の場合、またはこの値がレジストリに存在しない場合は、印刷ジョブの既定のクライアント側レンダリングが有効になります。
値 1 を指定すると、印刷ジョブのクライアント側レンダリングが無効になります。
ForceClientSideRendering REG_DWORD 値が 0 の場合、またはこの値がレジストリに存在しない場合は、印刷ジョブがクライアントにレンダリングされます。 印刷ジョブをクライアントでレンダリングできない場合は、サーバーにレンダリングされます。 印刷ジョブをサーバーにレンダリングできない場合は、失敗します。
値 1 を指定すると、クライアントに印刷ジョブがレンダリングされます。 印刷ジョブをクライアントにレンダリングできない場合は、失敗します。

必要条件

要件 値
サポートされている最小のクライアント
 Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー
 Windows 2000 Server [デスクトップ アプリのみ]
ヘッダー
Winspool.h (Windows.h を含む)
ライブラリ
Winspool.lib
[DLL]
Winspool.drv
Unicode 名と ANSI 名
 SetPrinterDataExW (Unicode) と SetPrinterDataExA (ANSI)

関連項目

印刷

印刷スプーラー API 関数

GetPrinterDataEx

OpenPrinter

SetPrinter

PRINTER_INFO_7