Función StartXpsPrintJob (xpsprint.h)
[StartXpsPrintJob no se admite y puede modificarse o no estar disponible en el futuro. ]
Comienza a imprimir una secuencia de documentos XPS en una impresora.
Sintaxis
HRESULT StartXpsPrintJob(
[in] LPCWSTR printerName,
[in] LPCWSTR jobName,
[in] LPCWSTR outputFileName,
[in] HANDLE progressEvent,
[in] HANDLE completionEvent,
[in] UINT8 *printablePagesOn,
[in] UINT32 printablePagesOnCount,
[out] IXpsPrintJob **xpsPrintJob,
[out] IXpsPrintJobStream **documentStream,
[out] IXpsPrintJobStream **printTicketStream
);
Parámetros
[in] printerName
Nombre de la impresora con la que se asociará este trabajo.
[in] jobName
Nombre de trabajo especificado por el usuario que se va a asociar a este trabajo. Si el trabajo no requiere un nombre independiente especificado por el usuario, este parámetro se puede establecer en NULL.
[in] outputFileName
Nombre de archivo del archivo o puerto en el que se redirigirá la salida de este trabajo. Establecer este valor hará que la salida del trabajo de impresión se dirija al archivo o puerto especificados. Para enviar el trabajo de impresión a la impresora especificada por printerName, este parámetro debe establecerse en NULL.
[in] progressEvent
Identificador de eventos que se señala cuando se producen 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.
XpS Print API no restablece este evento, es responsabilidad del autor de la llamada.
Si no se requiere ninguna notificación de progreso, este parámetro se puede establecer en NULL.
[in] completionEvent
Identificador de eventos que se señala cuando finaliza el trabajo de impresión. Se garantiza que este evento se señaliza exactamente una vez por cada llamada a StartXpsPrintJob . XpS Print API no restablece este evento, es responsabilidad del autor de la llamada.
Si no se requiere ninguna notificación de finalización, este parámetro se puede establecer en NULL.
[in] printablePagesOn
El parámetro hace referencia a una matriz UINT8 cuyos elementos especifican un subconjunto de las páginas de un documento que se van a imprimir. Como se muestra en la tabla siguiente, el valor de cada elemento indica si se va a imprimir la página.
| Valor del elemento Array | Significado |
|---|---|
|
No imprima la página. |
|
Imprima la página. |
Los eventos de progreso se señalarán solo para las páginas que se designan para la impresión.
Los elementos de la matriz representan todas las páginas designadas para imprimir, en todos los documentos del paquete XPS. Por ejemplo, si el paquete contiene dos documentos que tienen tres páginas cada una, la matriz que se muestra en la tabla siguiente designa la impresión de las páginas 0 y 2 del documento 1, y las páginas 0 y 2 del documento 2.
| Índice de elementos | Valor del elemento | ¿Impresión? | Número de documento | Número de página |
|---|---|---|---|---|
| 5 | 1 | Sí | 2 | 2 |
| 4 | 0 | No | 2 | 1 |
| 3 | 1 | Sí | 2 | 0 |
| 2 | 1 | Sí | 1 | 2 |
| 1 | 0 | No | 1 | 1 |
| 0 | 1 | Sí | 1 | 0 |
Si printablePagesOn es NULL, se imprimirán todas las páginas del paquete.
Si printablePagesOn tiene más elementos de los que hay páginas en el paquete, se omitirán los elementos superfluos.
Si la matriz tiene menos elementos de los que hay páginas en el documento, el valor del último elemento de matriz de la matriz se aplica a las páginas restantes. Esta regla facilita la especificación de un intervalo que está abierto o que obtiene solo unas pocas páginas de un documento grande impreso.
[in] printablePagesOnCount
Número de elementos de la matriz a los que hace referencia printablePagesOn. Si printablePagesOn es NULL, se omite este parámetro.
[out] xpsPrintJob
Puntero a la interfaz IXpsPrintJob que representa el trabajo de impresión creado por StartXpsPrintJob. Para obtener el estado del trabajo de impresión o cancelarlo, use la interfaz IXpsPrintJob . Si no se requiere un IXpsPrintJob , este parámetro se puede establecer en NULL.
[out] documentStream
Puntero a la interfaz IXpsPrintJobStream en la que el autor de la llamada escribe el documento XPS que va a imprimir este trabajo de impresión.
[out] printTicketStream
Puntero a la interfaz IXpsPrintJobStream que usa el autor de la llamada para escribir el vale de impresión de nivel de trabajo que se asociará a este trabajo. Si este parámetro se establece en NULL, se usarán los vales de impresión (si existen) del documento XPS escrito en documentStream .
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 |
|---|---|
|
El método se ha llevado a cabo de forma correcta. |
|
printerName o documentStream es NULL. |
|
Memoria insuficiente para crear un nuevo objeto IXpsPrintJob . |
Comentarios
StartXpsPrintJob es una función asincrónica, que puede devolver antes de que el administrador de trabajos de impresión cree o inicie un trabajo de impresión.
Las interfaces que se devuelven en xpsPrintJob, documentStream e printTicketStream no se deben usar hasta que StartXpsPrintJob se haya devuelto correctamente.
Después de que el autor de la llamada empiece a enviar datos, debe 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 finalice el trabajo de impresión, ya sea correctamente o no, el evento que se pasa en completionEvent se señala una y solo una vez. Para evitar la pérdida de datos, el autor de la llamada debe supervisar este evento y el subproceso o la aplicación del autor de la llamada no deben finalizar hasta que se haya señalado el evento.
El administrador de trabajos no almacena ni pone en cola los estados del trabajo. Dado que el procesamiento del trabajo no espera a que se lea el estado después de que se indiquen los eventos, el autor de la llamada podría perder algunos cambios de estado, dependiendo 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 haber recibido la notificación.
Si se produce un error en una llamada a StartXpsPrintJob , se actualizará el estado del trabajo, se indicarán los eventos de finalización y progreso y se devolverá un código de error. Para obtener el estado del trabajo de impresión con errores, llame a IXpsPrintJob::GetJobStatus.
StartXpsPrintJob llama a DuplicateHandle en completionEvent y progressEvent para asegurarse de que siguen siendo válidos durante la vigencia del trabajo. Dado que el administrador de trabajos de impresión usa un identificador duplicado para los eventos, es posible que el autor de la llamada cierre estos identificadores en cualquier momento sin afectar a la ejecución del trabajo. Sin embargo, el procedimiento recomendado es que el autor de la llamada cierre estos identificadores solo después de que el autor de la llamada haya señalado y observado el evento completionEvent .
Las interfaces IXpsPrintJobStream que se devuelven en documentStream e printTicketStream son secuencias de solo escritura que no permiten la búsqueda, pero que se pueden cerrar. El autor de la llamada escribe el documento XPS e imprime el contenido del vale en estas secuencias y, a continuación, llama a Close después de que se hayan escrito todos los datos. Las llamadas al método Write de las secuencias son seguras para subprocesos; Sin embargo, si estas llamadas se realizan desde subprocesos diferentes, no se garantiza que se confirmen en la secuencia en el orden esperado.
Requisitos
| Cliente mínimo compatible | Windows 7 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 R2 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | xpsprint.h |
| Library | XpsPrint.lib |
| Archivo DLL | XpsPrint.dll |
Vea también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de