Función StartXpsPrintJob1 (xpsprint.h)

[StartXpsPrintJob1 no se admite y puede modificarse o no estar disponible en el futuro. ]

Crea un trabajo de impresión para enviar contenido de documento XPS a una impresora. Esta función crea una ruta de acceso de impresión más eficaz que StartXpsPrintJob.

Sintaxis

HRESULT StartXpsPrintJob1(
  [in]            LPCWSTR             printerName,
  [in, optional]  LPCWSTR             jobName,
  [in, optional]  LPCWSTR             outputFileName,
  [in, optional]  HANDLE              progressEvent,
  [in, optional]  HANDLE              completionEvent,
  [out, optional] IXpsPrintJob        **xpsPrintJob,
  [out]           IXpsOMPackageTarget **printContentReceiver
);

Parámetros

[in] printerName

Nombre de la impresora con la que se asociará este trabajo.

[in, optional] jobName

Nombre de trabajo especificado por el usuario que se va a asociar a este trabajo. Puede establecer este parámetro en NULL si el trabajo no requiere un nombre independiente especificado por el usuario.

[in, optional] outputFileName

Nombre de archivo del archivo o puerto en el que se redirigirá la salida de este trabajo. Si se establece este valor, la salida del trabajo de impresión se dirigirá al archivo o puerto especificados. Para enviar el trabajo de impresión a la impresora especificada por printerName, debe establecer este parámetro en NULL.

[in, optional] progressEvent

Identificador de eventos que se señala cuando se produce uno de los siguientes cambios en el trabajo de impresión:

• Se asigna un identificador de trabajo al trabajo de impresión.
• La impresión de una página ha finalizado
• La impresión de un documento ha finalizado
• El trabajo de impresión se ha cancelado o ha finalizado debido a un error

Nota Este evento no se indicará hasta que la aplicación haya empezado a enviar datos al trabajo de impresión.

 

XpS Print API no restablece este evento, es responsabilidad del autor de la llamada.

Establezca este parámetro en NULL si no desea recibir una notificación sobre el progreso.

[in, optional] completionEvent

Identificador de eventos que se señala cuando finaliza el trabajo de impresión. Se garantiza que este evento se señale exactamente una vez por cada llamada a StartXpsPrintJob1 . XpS Print API no restablece este evento, es responsabilidad del autor de la llamada.

Establezca este parámetro en NULL si no desea recibir una notificación sobre la finalización.

[out, optional] xpsPrintJob

Puntero a la interfaz IXpsPrintJob que representa el trabajo de impresión que creó StartXpsPrintJob1 . Para obtener el estado del trabajo de impresión o cancelarlo, use la interfaz IXpsPrintJob . Establezca este parámetro en NULL si no lo necesita.

[out] printContentReceiver

Puntero a la interfaz IXpsOMPackageTarget que creó esta función. Este parámetro es necesario y no se puede establecer en NULL.

Para enviar contenido de documento al trabajo de impresión que creó esta función, use la interfaz IXpsOMPackageWriter que cree llamando al método CreateXpsOMPackageWriter de la interfaz IXpsOMPackageTarget devuelta en xpsOMPackageTarget.

Valor devuelto

El método devuelve un valor HRESULT. Entre los valores posibles se incluyen los que se indican en la tabla siguiente, entre otros.

Código devuelto	Descripción
S_OK	El método se ha llevado a cabo de forma correcta.
E_POINTER	printerName o xpsOMPackageTarget es NULL.
E_OUTOFMEMORY	Memoria insuficiente para crear un nuevo objeto IXpsPrintJob .

Comentarios

StartXpsPrintJob1 es una función asincrónica y, por tanto, puede volver antes de que el administrador de trabajos de impresión cree o inicie un trabajo de impresión.

No use las interfaces que se devuelven en xpsPrintJob y xpsOMPackageTarget hasta que StartXpsPrintJob1 se haya devuelto correctamente.

Después de que el autor de la llamada empiece a enviar datos, es una buena práctica de programación supervisar los eventos de progreso que se indican al evento que se pasa en progressEvent. Cuando se señala el evento, el autor de la llamada debe llamar a IXpsPrintJob::GetJobStatus para obtener el estado actual del trabajo de impresión.

Cuando el trabajo de impresión finaliza, ya sea correctamente o no, el evento que se pasa en completionEvent se señala solo una vez. Para evitar la pérdida de datos, es una buena práctica de programación para que el autor de la llamada supervise el evento de finalización y asegúrese de que ni el subproceso ni la aplicación que creó el trabajo de impresión finalizan hasta que se haya señalado el evento de finalización.

El administrador de trabajos no almacena ni pone en cola los estados de trabajo. Dado que el procesamiento del trabajo no espera a que se lea el estado después de indicar los eventos, el autor de la llamada podría perder algunos cambios de estado, en función del retraso entre el momento en que la aplicación recibió la notificación de cambio y la hora a la que llamó IXpsPrintJob::GetJobStatus. Para recibir notificaciones posteriores, la aplicación debe restablecer el evento de progreso después de recibir la notificación.

Si se produce un error en una llamada a StartXpsPrintJob1 , el administrador de trabajos de impresión actualiza el estado del trabajo, indica los eventos de finalización y progreso y devuelve un código de error. Para obtener el estado del trabajo de impresión con errores, llame a IXpsPrintJob::GetJobStatus.

StartXpsPrintJob1 llama a DuplicateHandle en completionEvent y progressEvent para asegurarse de que permanecen válidos durante la vigencia del trabajo. Dado que el administrador de trabajos de impresión usa un identificador duplicado para los eventos, el autor de la llamada puede cerrar estos identificadores en cualquier momento sin afectar a la ejecución del trabajo. Sin embargo, se recomienda que el autor de la llamada cierre estos identificadores solo después de que se haya señalado el evento completionEvent y el autor de la llamada lo haya observado.

Nota Cuando la aplicación se imprime en un archivo, la aplicación es responsable de proporcionar el valor para pasar el parámetro outputFileName para las operaciones de impresión a archivo. Para imprimir en una impresora que use un controlador que se envía al puerto FILE: , el autor de la llamada debe recuperar el nombre de archivo del usuario mostrando el cuadro de diálogo archivo común.

 

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7 con SP1, Windows Vista y Complemento de actualización de plataforma para Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 R2 con SP1, Windows Server 2008 y Complemento de actualización de plataforma para Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	xpsprint.h
Library	XpsPrint.lib
Archivo DLL	XpsPrint.dll

Vea también

Documentos

IXpsOMPackageTarget

IXpsOMPackageWriter

XML Paper Specification