Yazdırma Desteği Uygulaması v3 API'si tasarım kılavuzu

Bu makalede, cihazları için v3 Yazdırma Desteği Uygulaması (PSA) uygulayan yazıcı OEM'leri ve IHV'leri için yönergeler ve örnekler sağlanmaktadır.

Terminoloji

Terim	Tanım
PSA	Yazdırma Desteği Uygulaması. Bu belgede API'yi kullanan UWP uygulaması.
IPP	İnternet Yazdırma Protokolü. Yazdırma tercihlerini alıp ayarlamak ve yazdırılacak belgeyi göndermek üzere yazıcıyla etkileşim kurmak için bir istemci cihazdan kullanılır.
Yazdırma Desteğiyle İlişkili Yazıcı	PSA'ya bağlı Fiziksel IPP Yazıcısı.
IPP Yazıcısı	IPP protokollerini destekleyen yazıcı.
PDL	Sayfa tanımlama dili. Belgenin yazıcıya gönderildiği biçim.
İlişkili PSA Yazıcısı	PSA uygulamasıyla ilişkilendirilmiş fiziksel IPP yazıcı.
Yazıcı Cihazı Yetkinlikleri	Yazıcı özelliklerini tanımlamak için XML belge biçimi.
Yazdırma Destek Uzantısı	Yazıcı kısıtlama uzantısı özellikleri sağlamakla sorumlu PSA arka plan görevi.

Yazdırma desteği uygulaması v3 API'si

Bu makale, Yazdırma desteği uygulaması tasarım kılavuzunda açıklanan mevcut Yazdırma Desteği Uygulaması genel API'sinin v3 uzantılarını ve Windows.Graphics.Printing.PrintSupport Ad Alanını içerir. PSA API, yazıcı üreticilerinin, özel sürücü geliştirmeye gerek kalmadan, önceden yüklenmiş Microsoft IPP Sınıf Sürücüsü'nü kullanarak Windows kullanıcılarının yazdırma deneyimini geliştirebilecek Donanım Desteği uygulamaları geliştirmesine olanak tanır. Yazdırma bileşenleri, PSA aracısı süreci vasıtasıyla PSA uygulamasıyla iletişim kurar.

Daha fazla bilgi için aşağıdaki makalelere bakın:

Konu	Açıklama
Yazdırma Desteği Uygulaması tasarım kılavuzu	Cihazları için bir yazdırma destek uygulaması (PSA) uygulayan yazıcı OEM'leri ve IHV'ler için rehberlik ve örnekler sağlar.
Yazdırma Desteği Uygulaması v4 API tasarım kılavuzu	Cihazları için v4 Yazdırma Desteği Uygulaması (PSA) uygulayan yazıcı OEM'leri ve IHV'leri için rehberlik ve örnekler sağlar.
Yazdırma Desteği Sanal Yazıcı ile ilgili MSIX Bildirim Belirtimi	Yazdırma Desteği Sanal Yazıcısı uygulayan yazıcı OEM'leri ve IHV'ler için MSIX bildirim kılavuzu ve örnekleri sağlar.
Yazdırma destek uygulaması eşlemesi	Yazdırma desteği uygulamasını (PSA) yazıcıyla ilişkilendirmek için rehberlik ve örnekler sağlar.

API'nin önemli uzantıları şunlardır:

IPP sıkıştırma - PSA v3 API, bu özelliği destekleyen IPP yazıcıları için bir yazdırma işine IPP sıkıştırma özelliği ekleyerek IPP yazdırmayı geliştirmeye yönelik bir özellik ekler. Bazı PSA'larda özel sıkıştırma olabilir; bu da IPP işinin performansı etkileyen çift sıkıştırması olduğu anlamına gelir. Bunu azaltmak için, PSA v3 API, IsIppCompressionEnabled adında bir özellik ve gerektiğinde geçerli iş için sıkıştırmayı devre dışı bırakmak üzere kullanılabilecek DisableIppCompressionForJob işlevi, PrintWorkflowJobStartingEventArgs (PSA v1 API) çalışma zamanı sınıfında tanıtır.
IPP İşi Hata İşleme ve Hata Bildirimi - PSA v3 API, PSA v1 API çalışma zamanı sınıfından PrintWorkflowJobBackgroundSession içinde JobIssueDetected olayını tanıtır. PSA, yazdırma işinde bir hata veya uyarı algıladığında olay tetiklenir. PSA daha sonra kullanıcıya hata bildirimini göstermekten sorumludur. PSA bu olay için kaydolduğunda ve PrintWorkflowJobIssueDetectedEventArgs içinde SkipSystemErrorToast özelliğini true olarak ayarladığında, yazdırma sistemine Windows yazdırma sisteminin bildirimini göstermemesi gerektiğini bildirir. PSA v3 API'sinde, kullanıcı bir bildirimle etkileştiğinde PSA'nın kullanıcı arabirimini başlatması için bir mekanizma da sağlanır.
Özel IPP iletişim zaman aşımları - PSA v3 API,PSA'nın IPP zaman aşımlarını geçersiz kabileceği bir API sağlar. Ayrıca, PrintSupportIppCommunicationConfiguration çalışma zamanı sınıfı, IPP iletişim zaman aşımlarını yönetmek amacıyla PrintSupportPrintDeviceCapabilitiesChangedEventArgs'e eklenmiştir. Buna ek olarak, PSA v3 API'sinde IPP iletişimiyle ilgili bir hata oluştuğunda tetiklenen bir olay bulunur. Olay, IHV'nin hatayı araştırabilmesi ve zaman aşımı değerlerini buna göre ayarlayabilmesi için tanıtıldı.
Destek IPPFaxOut - PSA v3 API, IPPFaxOut yazıcıları desteklemek için yazdırma sistemine bir özellik ekler. PSA, Faks'ı desteklemek için XPS'yi Tiff'e dönüştürmek için bir işleme filtresini destekler. PSA, TIFF'ye dönüştürmeden önce XPS içeriğini işleyebileceğinden, PSA'nın XPS'ye TIFF dönüştürücüsünü erişebilmesi için PrintWorkflowPdlConversionType XpsToTiff sabit listesi değerini sağlar. Ayrıca, PSA'nın standart yazıcı ile IPPFaxOut yazıcıları arasında ayrım edebilmesi için IppPrintDevice çalışma zamanı sınıfına IsIPPFaxOutPrinter özelliği sağlar.

IPP sıkıştırmasını devre dışı bırakma

IPP sıkıştırması aşağıdaki kod örneğinde gösterilmiştir.

public sealed class PrintSupportWorkflowBackgroundTask : IBackgroundTask
{
    public BackgroundTaskDeferral TaskInstanceDeferral { get; set; }
    private PrintWorkflowJobBackgroundSession session;

    public void Run(IBackgroundTaskInstance taskInstance)
    {
        TaskInstanceDeferral = taskInstance.GetDeferral();

        if (taskInstance.TriggerDetails is PrintWorkflowJobTriggerDetails jobDetails)
        {
            session = jobDetails.PrintWorkflowJobSession;
            session.JobStarting += OnJobStarting;
            session.PdlModificationRequested += OnPdlModificationRequested;
            session.JobIssueDetected += OnJobIssueDetected;

            // Make sure to register all the event handlers before PrintWorkflowJobBackgroundSession.Start is called.
            session.Start();
        }
    }

    private void OnJobStarting(PrintWorkflowJobBackgroundSession sender, PrintWorkflowJobStartingEventArgs args)
    {
        using (args.GetDeferral())
        {
            // Skip system rendering.
            args.SetSkipSystemRendering();

            // If Ipp compression is enabled by the system, check to see if PSA does custom compression for the printer
            // and disable system compression if required.
            if (args.IsIppCompressionEnabled)
            {
                if (this.HasCustomCompression(args.Printer))
                {
                    args.DisableIppCompressionForJob();
                }
            }
        }
    }

    bool HasCustomCompression(IppPrintDevice device)
    {
        bool hasCustomCompression = false;
        // Check if the PSA does custom compression for the printer
        return hasCustomCompression;
    } 
}

IPP hata işleme işiyle ilgili

Bu örnek, PSA uygulamasının iş hatalarına nasıl kaydolabileceğini, iş hataları için bildirimleri nasıl gösterebileceğini ve kullanıcı bildirimleri etkinleştirdiğinde kullanıcı arabirimini nasıl başlatabileceğini gösterir.

public sealed class PrintSupportWorkflowBackgroundTask : IBackgroundTask
{
    public BackgroundTaskDeferral TaskInstanceDeferral { get; set; }
    private PrintWorkflowJobBackgroundSession session;

    public void Run(IBackgroundTaskInstance taskInstance)
    {
        TaskInstanceDeferral = taskInstance.GetDeferral();

        if (taskInstance.TriggerDetails is PrintWorkflowJobTriggerDetails jobDetails)
        {
            session = jobDetails.PrintWorkflowJobSession;
            session.JobStarting += OnJobStarting;
            session.PdlModificationRequested += OnPdlModificationRequested;
            session.JobIssueDetected += OnJobIssueDetected;

            // Make sure to register all the event handlers before PrintWorkflowJobBackgroundSession.Start is called.
            session.Start();
        }
    }

    private void OnJobIssueDetected (PrintWorkflowJobBackgroundSession sender, PrintWorkflowJobIssueDetectedEventArgs args)
    {
        // Using a deferral to exclude the background process from being suspended while PSA displays UI.
        Deferral deferral = args.GetDeferral();
        var toast = new ToastNotification(GetErrorToastXml(args.ExtendedError,
                args.JobIssueKind, args.PrinterJob, args.Configuration));
        toast.Activated += async (toastSender, e) =>
        {
            // PSA UI application 
            PrintWorkflowUICompletionStatus uiStatus = await args.UILauncher.LaunchAndCompleteUIAsync();
            // Complete deferral
            deferral.Complete();
        };
        toast.Dismissed += async (toastSender, e) => { deferral.Complete(); };
        toast.Failed += async (toastSender, e) => { deferral.Complete(); };
            
        ToastNotificationManager.CreateToastNotifier().Show(toast);
        args.SkipSystemErrorToast = true;
    }

    private XmlDocument GetErrorToastXml(Exception jobError, PrintWorkflowJobIssueKind issueKind,
        PrintWorkflowPrinterJob printerJob, PrintWorkflowConfiguration workflowConfig )
    {
        var errorToastXml = new XmlDocument();
        // Generate Toast XML based on error information from Exception and PrintWorkflowPrinterJob.
        return errorToastXml;
    }
}

IPP iletişim zaman aşımını ayarlama

Bu örnekte IPP iletişim zaman aşımının nasıl ayarlanacağı gösterilmektedir.

public sealed class PrintSupportExtensionBackGroundTask : IBackgroundTask
{
    public BackgroundTaskDeferral TaskInstanceDeferral { get; set; }
    private PrintSupportExtensionSession session;

    public void Run(IBackgroundTaskInstance taskInstance)
    {
        taskInstance.Canceled += OnTaskInstanceCanceled;
        TaskInstanceDeferral = taskInstance.GetDeferral();

        if (taskInstance.TriggerDetails is PrintSupportExtensionTriggerDetails extensionDetails)
        {
            session = extensionDetails.Session;
            session.PrintTicketValidationRequested += OnSessionPrintTicketValidationRequested;
            session.PrintDeviceCapabilitiesChanged += OnSessionPrintDeviceCapabilitiesChanged;
            session.CommunicationErrorDetected += OnCommunicationErrorDetected;

            // Make sure to register all the event handlers before PrintSupportExtensionSession.Start is called.
            session.Start();
        }
    }

    private void OnTaskInstanceCanceled(IBackgroundTaskInstance sender, BackgroundTaskCancellationReason reason)
    {
        session = null;
        TaskInstanceDeferral.Complete();
    }
    
    private void OnSessionPrintDeviceCapabilitiesChanged(PrintSupportExtensionSession sender, PrintSupportPrintDeviceCapabilitiesChangedEventArgs args)
    {
        // Using deferral to exclude the background process from being suspended while PSA updates the printer PDC and other configurations.
        using (args.GetDeferral())
        {
            if (args.CommunicationConfiguration.CanModifyTimeouts)
                {
                    this.UpdateAttributeTimeouts(args.CommunicationConfiguration, sender.Printer);
                    this.UpdateJobTimeouts(args.CommunicationConfiguration, sender.Printer);
                }
                // Do other operations, such as Updating PDC, PDR, and so on here.
        }
    }

    void UpdateAttributeTimeouts(PrintSupportIppCommunicationConfiguration config, IppPrintDevice device)
    {
        IppPrinterCommunicationKind communicationKind = config.CommunicationKind;
        PrintSupportIppCommunicationTimeouts currentTimeouts = config.IppAttributeTimeouts;

        // Adjust attribute timeouts based on the printer
        switch (communicationKind)
        {
            case IppPrinterCommunicationKind.Network:
                currentTimeouts.ConnectTimeout = TimeSpan.FromSeconds(10);
                currentTimeouts.SendTimeout = TimeSpan.FromSeconds(10);
                currentTimeouts.ReceiveTimeout = TimeSpan.FromSeconds(10);
                break;
            case IppPrinterCommunicationKind.UniversalPrint:
                // adjust timeout for universal printer
                break;
        }
        
    }

    void UpdateJobTimeouts(
        PrintSupportIppCommunicationConfiguration config, IppPrintDevice device)
    {
        IppPrinterCommunicationKind communicationKind = config.CommunicationKind;
        PrintSupportIppCommunicationTimeouts currentTimeouts = config.IppJobTimeouts;
        // Adjust job timeouts based on the printer and communication type
        switch (communicationKind)
        {
            case IppPrinterCommunicationKind.Network:
                currentTimeouts.ConnectTimeout = TimeSpan.FromSeconds(30);
                currentTimeouts.SendTimeout = TimeSpan.FromSeconds(30);
                currentTimeouts.ReceiveTimeout = TimeSpan.FromSeconds(30);
                break;
            case IppPrinterCommunicationKind.UniversalPrint:
                // adjust timeout for universal printer
                break;
        }
    }
}

IPP iletişim hatalarını işleme

Bu örnek, IPP iletişim hatalarının nasıl işleneceğini gösterir.

public sealed class PrintSupportExtensionBackGroundTask : IBackgroundTask
{
    public BackgroundTaskDeferral TaskInstanceDeferral { get; set; }
    private PrintSupportExtensionSession session;
    public void Run(IBackgroundTaskInstance taskInstance)
    {
        taskInstance.Canceled += OnTaskInstanceCanceled;
        TaskInstanceDeferral = taskInstance.GetDeferral();

        if (taskInstance.TriggerDetails is PrintSupportExtensionTriggerDetails extensionDetails)
        {
            session = extensionDetails.Session;
            session.PrintTicketValidationRequested += OnSessionPrintTicketValidationRequested;
            session.PrintDeviceCapabilitiesChanged += OnSessionPrintDeviceCapabilitiesChanged;
            session.CommunicationErrorDetected += OnCommunicationErrorDetected ;

            // Make sure to register all the event handlers before PrintSupportExtensionSession.Start is called.
            session.Start();
        }
    }

    private void OnTaskInstanceCanceled(IBackgroundTaskInstance sender, BackgroundTaskCancellationReason reason)
    {
        session = null;
        TaskInstanceDeferral.Complete();
    }

    private void OnCommunicationErrorDetected(PrintSupportExtensionSession sender, PrintSupportCommunicationErrorDetectedEventArgs args)
    {
        // Using deferral to exclude the background process from being suspended while PSA updates the timeouts.
        using (args.GetDeferral())
        {

            if (args.ErrorKind == IppCommunicationErrorKind.Timeout)
            {
                PrintSupportIppCommunicationConfiguration ippConfig = args.CommunicationConfiguration;
                IppPrintDevice device = sender.Printer;
                // Update timeout based on the communication error
            }
        }
    }  
}

PSA'da IPP faks yazıcısına yazdırma

Bu örnek, PSA'daki bir IPPFaxOut yazıcısına nasıl yazdırılacağını gösterir.

public sealed class PrintSupportWorkflowBackgroundTask : IBackgroundTask
{
    public BackgroundTaskDeferral TaskInstanceDeferral { get; set; }
    private PrintWorkflowJobBackgroundSession session;

    public void Run(IBackgroundTaskInstance taskInstance)
    {
        TaskInstanceDeferral = taskInstance.GetDeferral();

        if (taskInstance.TriggerDetails is PrintWorkflowJobTriggerDetails jobDetails)
        {
            session = jobDetails.PrintWorkflowJobSession;
            session.JobStarting += OnJobStarting;
            session.PdlModificationRequested += OnPdlModificationRequested;
            session.JobIssueDetected += OnJobIssueDetected;

            // Make sure to register all the event handlers before PrintWorkflowJobBackgroundSession.Start is called.
            session.Start();
        }
    }

    private async void OnPdlModificationRequested(PrintWorkflowJobBackgroundSession sender, PrintWorkflowPdlModificationRequestedEventArgs args)
    {
        using (args.GetDeferral())
        {
            IppPrintDevice printer = args.PrinterJob.Printer;
            IInputStream xpsContent = args.SourceContent.GetInputStream();
            WorkflowPrintTicket printTicket = args.PrinterJob.GetJobPrintTicket();

            string documentFormat = this.GetPrinterDocumentFormat(printer);
            PrintWorkflowPdlTargetStream targetStream = args.CreateJobOnPrinter(documentFormat);
            IInputStream xpsSourceContent = xpsContent;
            if (printer.IsIPPFaxOutPrinter)
            {                    
                // Add cover page to XPS source document   
                xpsSourceContent = this.AddCoverPageToXpsContent(xpsContent);
            }
            
            PrintWorkflowPdlConverter pdlConverter;
            switch (documentFormat.ToLowerInvariant())
            {
                case "image/pwg-raster":
                    pdlConverter = args.GetPdlConverter(PrintWorkflowPdlConversionType.XpsToPwgr);
                    break;
                case "application/pclm":
                    pdlConverter = args.GetPdlConverter(PrintWorkflowPdlConversionType.XpsToPclm);
                    break;
                case "application/pdf":
                    pdlConverter = args.GetPdlConverter(PrintWorkflowPdlConversionType.XpsToPdf);
                    break;
                case "image/tiff":
                    pdlConverter = args.GetPdlConverter(PrintWorkflowPdlConversionType.XpsToTiff);
                    break;
                default:
                    // This should not happen, aborting workflow if PSA does not identify the supported PDLs
                    args.Configuration.AbortPrintFlow(PrintWorkflowJobAbortReason.JobFailed);
                    return;
                }
                // Use pdlConverter to convert the source XPS stream to printer's document format and send it to the printer using targetStream.
                await pdlConverter.ConvertPdlAsync(printTicket, xpsSourceContent, targetStream.GetOutputStream());

                targetStream.CompleteStreamSubmission(PrintWorkflowSubmittedStatus.Succeeded);
            }
        }

    private IInputStream AddCoverPageToXpsContent(IInputStream xpsStream)
    {
        var coverPageXps = new InMemoryRandomAccessStream();
        // Add cover page to XPS content and write to coverPageXps stream
        return coverPageXps;
    }
}

PSA sistemi üzerinden telefon numarası için Faks kullanıcı arayüzünü devre dışı bırakma

IPP faks yazıcısının desteğiyle bu örnekte, kullanıcıdan Faks yazıcısına yazdırırken Faks numarasını girmesini istemeye yönelik bir kullanıcı arabirimi gösterilir. Ancak PSA, daha fazla bilgi ve seçenekle kendi kullanıcı arabirimini göstermek isteyebilir. Faks için iki kullanıcı arabirimi olması kullanıcı açısından kafa karıştırıcı olduğundan, bu örnek, PSA'nın Faks kullanıcı arabirimini göstermek istediğinde sistem kullanıcı arabirimini devre dışı bırakması için bir seçenek gösterir.

Aşağıdaki örnekte API kullanımı gösterilmektedir.

public sealed class PrintSupportWorkflowBackgroundTask : IBackgroundTask
{

    private void OnJobStarting(PrintWorkflowJobBackgroundSession sender, PrintWorkflowJobStartingEventArgs args)
    {
        using (args.GetDeferral())
        {
            // If the job is printing to an Ipp fax printer,
            // check whether PSA has a custom UI and disable system UI for getting the fax number.
            if (args.IsIPPFaxOutPrinter)
            {
                if (this.HasCustomUIForFax(args.Printer))
                {
                    args.SkipSystemFaxUI = true;
                }
            }
        }
    }

    bool HasCustomUIForFax(IppPrintDevice device)
    {
        bool hasCustomUIForFax = false;
        // Check if the PSA does custom UI for the given fax printer.
        return hasCustomUIForFax;
    }  
}

Açıklamalar

Bu makaledeki örnekler, geliştiricinin PSA API iş akışına aşina olduğu varsayımıyla Yazdırma desteği uygulaması tasarım kılavuzundaki PSA v1 ve v2 API örneklerinin üzerine kurulmuştur.

Bu makale, Yazdırma Desteği Uygulaması tasarım kılavuzunda ve Windows.Graphics.Printing.PrintSupport Ad Alanı'nda açıklanan mevcut genel Yazdırma Desteği Uygulaması API'sinin uzantılarını içerir. PSA API, yazıcı üreticilerinin özel sürücü geliştirmeye gerek kalmadan gömülü Microsoft IPP Sınıf Sürücüsü kullanırken Windows kullanıcılarının yazdırma deneyimini geliştirebilecek UWP uygulamaları geliştirmesine olanak tanır.

Yazdırma bileşenleri PSA aracı işlemi aracılığıyla PSA uygulamasıyla iletişim kurar.

DisableIppCompressionForJob

Windows'da üçüncü taraf yazıcı sürücüleri için hizmet sonu planı

IsIppCompressionEnabled

IsIPPFaxOutPrinter

IppPrintDevice

İşSorunuTespitEdildi

YazdırmaDesteğiIppİletişimYapılandırması

PrintSupportPrintDeviceCapabilitiesChangedEventArgs

Baskı Çalışma Akışı İş Arka Plan Oturumu

PrintWorkflowJobIssueDetectedEventArgs

PrintWorkflowJobStartingEventArgs

PrintWorkflowPdlConversionType

SkipSystemErrorToast

Windows.Graphics.Printing.PrintSupport

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-01-14

Aracılığıyla paylaş

Yazdırma Desteği Uygulaması v3 API'si tasarım kılavuzu

Terminoloji