DocumentProperties-Funktion

Die DocumentProperties-Funktion ruft Druckerinitialisierungsinformationen ab oder ändert sie oder zeigt ein Eigenschaftenblatt für die Druckerkonfiguration für den angegebenen Drucker an.

Syntax

LONG DocumentProperties(
  _In_  HWND     hWnd,
  _In_  HANDLE   hPrinter,
  _In_  LPTSTR   pDeviceName,
  _Out_ PDEVMODE pDevModeOutput,
  _In_  PDEVMODE pDevModeInput,
  _In_  DWORD    fMode
);

Parameter

hWnd [in]

Ein Handle für das übergeordnete Fenster des Eigenschaftenblatts für die Druckerkonfiguration.

hPrinter [in]

Ein Handle für ein Druckerobjekt. Verwenden Sie die OpenPrinter - oder AddPrinter-Funktion , um einen Druckerhandle abzurufen.

pDeviceName [in]

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Namen des Geräts angibt, für das das Eigenschaftenblatt für die Druckerkonfiguration angezeigt wird.

pDevModeOutput [out]

Ein Zeiger auf eine DEVMODE-Struktur , die die vom Benutzer angegebenen Druckerkonfigurationsdaten empfängt.

pDevModeInput [in]

Ein Zeiger auf eine DEVMODE-Struktur , die das Betriebssystem zum Initialisieren der Eigenschaftenblattsteuerelemente verwendet.

Dieser Parameter wird nur verwendet, wenn das flag DM_IN_BUFFER im fMode-Parameter festgelegt ist. Wenn DM_IN_BUFFER nicht festgelegt ist, verwendet das Betriebssystem den Standardmäßigen DEVMODE des Druckers.

fMode [in]

Die Von der Funktion ausgeführten Vorgänge. Wenn dieser Parameter null ist, gibt die DocumentProperties-Funktion die Anzahl von Bytes zurück, die für die DEVMODE-Datenstruktur des Druckertreibers erforderlich sind. Verwenden Sie andernfalls eine oder mehrere der folgenden Konstanten, um einen Wert für diesen Parameter zu erstellen: Beachten Sie jedoch, dass eine Anwendung mindestens einen Eingabe- und einen Ausgabewert angeben muss, um die Druckeinstellungen zu ändern.

Wert	Bedeutung
DM_IN_BUFFER	Eingabewert. Vor der Aufforderung, dem Kopieren oder Aktualisieren führt die Funktion die aktuellen Druckeinstellungen des Druckertreibers mit den Einstellungen in der DEVMODE-Struktur zusammen, die durch den pDevModeInput-Parameter angegeben wird. Die -Funktion aktualisiert die Struktur nur für die Elemente, die vom dmFields-Element der DEVMODE-Struktur angegeben werden. Dieser Wert wird auch als DM_MODIFY definiert. Bei Konflikten während der Zusammenführung überschreiben die Einstellungen in der devmode-Struktur , die von pDevModeInput angegeben wird, die aktuellen Druckeinstellungen des Druckertreibers.
DM_IN_PROMPT	Eingabewert. Die Funktion zeigt das Eigenschaftenblatt print setup des Druckertreibers an und ändert dann die Einstellungen in der DEVMODE-Datenstruktur des Druckers auf die vom Benutzer angegebenen Werte. Dieser Wert wird auch als DM_PROMPT definiert.
DM_OUT_BUFFER	Ausgabewert. Die Funktion schreibt die aktuellen Druckeinstellungen des Druckertreibers, einschließlich privater Daten, in die DEVMODE-Datenstruktur , die durch den pDevModeOutput-Parameter angegeben wird. Der Aufrufer muss einen Puffer zuordnen, der ausreichend groß ist, um die Informationen zu enthalten. Wenn das DM_OUT_BUFFER-Bit eindeutig ist, kann der pDevModeOutput-ParameterNULL sein. Dieser Wert wird auch als DM_COPY definiert.

Rückgabewert

Wenn der fMode-Parameter null ist, entspricht der Rückgabewert der Größe des Puffers, der für die Initialisierungsdaten des Druckertreibers erforderlich ist. Beachten Sie, dass dieser Puffer größer als eine DEVMODE-Struktur sein kann, wenn der Druckertreiber private Daten an die Struktur anhängt.

Wenn die Funktion das Eigenschaftenblatt anzeigt, lautet der Rückgabewert entweder IDOK oder IDCANCEL, je nachdem, welche Schaltfläche der Benutzer auswählt.

Wenn die Funktion das Eigenschaftenblatt nicht anzeigt und erfolgreich ist, lautet der Rückgabewert IDOK.

Wenn die Funktion fehlschlägt, ist der Rückgabewert kleiner als 0 (null).

Bemerkungen

Hinweis

Dies ist eine blockierende oder synchrone Funktion, die möglicherweise nicht sofort zurückgegeben wird. Wie schnell diese Funktion zurückgibt, hängt von Laufzeitfaktoren wie Netzwerk-status, Druckserverkonfiguration und Druckertreiberimplementierungsfaktoren ab, die beim Schreiben einer Anwendung schwer vorherzusagen sind. Das Aufrufen dieser Funktion aus einem Thread, der die Interaktion mit der Benutzeroberfläche verwaltet, könnte dazu führen, dass die Anwendung nicht mehr reagiert.

Die Zeichenfolge, auf die der pDeviceName-Parameter verweist, kann durch Aufrufen der GetPrinter-Funktion abgerufen werden.

Die DEVMODE-Struktur , die tatsächlich von einem Druckertreiber verwendet wird, enthält den geräteunabhängigen Teil (wie oben definiert), gefolgt von einem treiberspezifischen Teil, der in Größe und Inhalt mit den einzelnen Treibern und Treiberversionen variiert. Aufgrund dieser Treiberabhängigkeit ist es für Anwendungen sehr wichtig, den Treiber nach der richtigen Größe der DEVMODE-Struktur abzufragen, bevor ein Puffer dafür zugewiesen wird.

Um Änderungen an druckeinstellungen vorzunehmen, die für eine Anwendung lokal sind, sollte eine Anwendung die folgenden Schritte ausführen:

1. Rufen Sie die Anzahl von Bytes ab, die für die vollständige DEVMODE-Struktur erforderlich sind, indem Sie DocumentProperties aufrufen und null im fMode-Parameter angeben.
2. Weisen Sie Arbeitsspeicher für die vollständige DEVMODE-Struktur zu.
3. Rufen Sie die aktuellen Druckereinstellungen ab, indem Sie DocumentProperties aufrufen. Übergeben Sie einen Zeiger auf die DEVMODE-Struktur , die in Schritt 2 als pDevModeOutput-Parameter zugeordnet ist, und geben Sie den DM_OUT_BUFFER Wert an.
4. Ändern Sie die entsprechenden Member der zurückgegebenen DEVMODE-Struktur , und geben Sie an, welche Member geändert wurden, indem Sie die entsprechenden Bits im dmFields-Member des DEVMODE-Elements festlegen.
5. Rufen Sie DocumentProperties auf, und übergeben Sie die geänderte DEVMODE-Struktur zurück als pDevModeInput - und pDevModeOutput-Parameter , und geben Sie die werte DM_IN_BUFFER und DM_OUT_BUFFER an (die mit dem OR-Operator kombiniert werden). Die DEVMODE-Struktur , die vom dritten Aufruf von DocumentProperties zurückgegeben wird, kann als Argument in einem Aufruf der CreateDC-Funktion verwendet werden.

Um ein Handle für einen Drucker-Gerätekontext mit den aktuellen Druckereinstellungen zu erstellen, müssen Sie DocumentProperties nur zweimal aufrufen, wie oben beschrieben. Der erste Aufruf ruft die Größe des vollständigen DEVMODE ab, und der zweite Aufruf initialisiert devMODE mit den aktuellen Druckereinstellungen. Übergeben Sie die initialisierte DEVMODE an CreateDC , um das Handle für den Druckergerätekontext abzurufen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Header	Winspool.h (Einschließen von Windows.h)
Bibliothek	Winspool.lib
DLL	Winspool.drv
Unicode- und ANSI-Name	DocumentPropertiesW (Unicode) und DocumentPropertiesA (ANSI)

Siehe auch

Drucken

Druckspooler-API-Funktionen

AdvancedDocumentProperties

CreateDC

DEVMODE

GetPrinter

OpenPrinter