How To Get the Status of a Printer and a Print Job

• Microsoft Win32 Application Programming Interface (API) for Windows NT & Win95, versions 3.51, 4.00 on the following platforms: Windows NT, Win95

SUMMARY

The status of printers and print jobs are updated by the Win32 Spooler during the despool of a print job. At all other times, when that printer is not despooling and reports no state information, it is considered to be ready and idle.

MORE INFORMATION

A Printer, as referred to by the Win32 API, is conceptually an entity comprising the printer driver, the print queue, and the input/output path to the physical printer. The operating system treats a physical printer as merely the destination of a print job generated by and passed through a system "Printer," referred to in the rest of this article as a Printer.

The most visible part of a Printer is a print queue. It is managed by the Print Manager or the Printer folders in the Windows 95-style user interfaces. The printer driver is the interface to the Printer that is used by applications to create print jobs via printer DCs. The I/O path for a Printer consists of several layers of system code culminating with a port monitor.

The port monitor is the interface to the physical printer at the down-stream end of a system Printer and is responsible for transferring the data of a print job across whatever connection exists to the physical printer. In the case of bi-directional printers, the port monitor would be responsible for transferring data to and from the physical printer. This connection, and the physical printer, are where errors occur. It is the job of the port monitor to report those errors.

The Spooler does not query for the state of a physical printer to which a Printer is connected. Instead, the state of a physical printer determines the success of a print job at the time it is despooled over the port monitor. If some error occurs in this process, the error is reported by the port monitor and recorded in a print job's status information. The Spooler, in turn, propagates reasonable error information to the Printer Queue.

Consequently, a system Printer reports no status when the Printer queue is empty. In this state, the Printer is assumed ready to accept print jobs. This is a valid assumption even if the physical printer is in an error state such as off-line. The operating system considers the Printer ready to accept print jobs even if, for some reason, it cannot complete delivery to the physical printer. Such a circumstance is considered an error state in the operating system that must be addressed by the user. It is not considered an error reportable to the application that is allowed to complete the spooling of the print job successfully.

Determining the State of a Physical Printer

Given this background, there is one fundamental premise that must be true to determine the state of a physical printer: The Spooler must be attempting to send a print job to the physical printer. This is the only time the state of the printer is reported by the port monitor. In addition, the most meaningful information may be reported in the status members of a JOB_INFO structure for that particular print job because some port monitor will have set these values directly.

The JOB_INFO structures contain a Status member and a pStatus member. Both members contain status information of a print job reported by the port monitor. These two members differ in that the Status member is a bit field of states that contains predetermined values, while the pStatus member is a pointer to a string that could contain just about anything. These values are documented by the Win32 SDK and the WinSpool.h header file. The pStatus member is sometimes, but not always, set to a descriptive status string. The contents of this string are defined by each port monitor.

JOB_INFO structures are returned by two API functions: GetJob and EnumJobs. EnumJobs returns an array of JOB_INFO structures without requiring that the caller reference a particular job in the Printer queue. The print job that is currently despooling (printing) will contain the status information. To find this job in the array, search the array of JOB_INFO structures to locate the print job whose Status member has the JOB_STATUS_PRINTING bit set.

The easier method of determining the status of a printer is to examine the Status member of a PRINTER_INFO structure. This structure is returned by the GetPrinter function. There is a disadvantage to this approach in that there is no pStatus string member in a PRINTER_INFO structure that might provide more detailed or extensive state information. However, there is an advantage in that a port monitor may set some of the more extensive printer status bits of the PRINTER_INFO structure. Note, however, that the default port monitor for Windows does not usually set more than the PRINTER_STATUS_ERROR bit of a Printer's Status member.

Note that the Status members of either set of structures may contain state information that is not strictly related to the physical printer. For example, the Status member of the PRINTER_INFO structures may be set with PRINTER_STATUS_PAUSED or PRINTER_STATUS_PENDING_DELETION, that are strictly relevant to the Print Queue. Also, the Status member of the JOB_INFO structure may contain state values for JOB_STATUS_PAUSED or JOB_STATUS_DELETING, that are relevant only to that particular print job. Note, also, that print jobs may accumulate in a Print queue after they have despooled and would be left with a state of JOB_STATUS_PRINTED.

Each of these functions requires a handle to a printer to identify the desired Printer. This handle is obtained from the OpenPrinter function, that accepts a string containing the name of the printer. This name can be either the local name of the printer or a UNC share name to a network printer.

The following code fragment demonstrates how to call the EnumJobs function properly to retrieve JOB_INFO structures and how to call the GetPrinter function to retrieve PRINTER_INFO structures:

   BOOL GetJobs(HANDLE hPrinter,        /* handle to the printer */
                JOB_INFO_2 **ppJobInfo, /* pointer to be filled  */
                int *pcJobs,            /* count of jobs filled  */
                DWORD *pStatus)         /* print Queue status    */
   {
       DWORD               cByteNeeded,
                           nReturned,
                           cByteUsed;
       JOB_INFO_2          *pJobStorage = NULL;
       PRINTER_INFO_2       *pPrinterInfo = NULL;

   /* Get the buffer size needed */
       if (!GetPrinter(hPrinter, 2, NULL, 0, &cByteNeeded))
       {
           if (GetLastError() != ERROR_INSUFFICIENT_BUFFER)
               return FALSE;
       }

       pPrinterInfo = (PRINTER_INFO_2 *)malloc(cByteNeeded);
       if (!(pPrinterInfo))
           /* failure to allocate memory */
           return FALSE;

       /* get the printer info */
       if (!GetPrinter(hPrinter,
               2,
               (LPSTR)pPrinterInfo,
               cByteNeeded,
               &cByteUsed))
       {
           /* failure to access the printer */
           free(pPrinterInfo);
           pPrinterInfo = NULL;
           return FALSE;
       }

       /* Get job storage space */
       if (!EnumJobs(hPrinter,
               0,
               pPrinterInfo->cJobs,
               2,
               NULL,
               0,
               (LPDWORD)&cByteNeeded,
               (LPDWORD)&nReturned))
       {
           if (GetLastError() != ERROR_INSUFFICIENT_BUFFER)
           {
               free(pPrinterInfo);
               pPrinterInfo = NULL;
               return FALSE;
           }
       }

       pJobStorage = (JOB_INFO_2 *)malloc(cByteNeeded);
       if (!pJobStorage)
       {
           /* failure to allocate Job storage space */
           free(pPrinterInfo);
           pPrinterInfo = NULL;
           return FALSE;
       }

       ZeroMemory(pJobStorage, cByteNeeded);

       /* get the list of jobs */
       if (!EnumJobs(hPrinter,
               0,
               pPrinterInfo->cJobs,
               2,
               (LPBYTE)pJobStorage,
               cByteNeeded,
               (LPDWORD)&cByteUsed,
               (LPDWORD)&nReturned))
       {
           free(pPrinterInfo);
           free(pJobStorage);
           pJobStorage = NULL;
           pPrinterInfo = NULL;
           return FALSE;
       }

       /*
        *  Return the information
        */
       *pcJobs = pPrinterInfo->cJobs;
       *pStatus = pPrinterInfo->Status;
       *ppJobInfo = pJobStorage;
       free(pPrinterInfo);

       return TRUE;
   }

   BOOL IsPrinterError(HANDLE hPrinter)
   {
       JOB_INFO_2  *pJobs;
       int         cJobs,
                   i;
       DWORD       dwPrinterStatus;

       /*
        *  Get the state information for the Printer Queue and
        *  the jobs in the Printer Queue.
        */
       if (!GetJobs(hPrinter, &pJobs, &cJobs, &dwPrinterStatus))
           return FALSE;

       /*
        *  if the Printer reports an error, believe it
        */
       if (dwPrinterStatus &
           (PRINTER_STATUS_ERROR |
           PRINTER_STATUS_PAPER_JAM |
           PRINTER_STATUS_PAPER_OUT |
           PRINTER_STATUS_PAPER_PROBLEM |
           PRINTER_STATUS_OUTPUT_BIN_FULL |
           PRINTER_STATUS_NOT_AVAILABLE |
           PRINTER_STATUS_NO_TONER |
           PRINTER_STATUS_OUT_OF_MEMORY |
           PRINTER_STATUS_OFFLINE |
           PRINTER_STATUS_DOOR_OPEN))
       {
           return TRUE;
       }

   /*
        *  Find the Job in the Queue that is printing
        */
       for (i=0; i < cJobs; i++)
       {
           if (pJobs[i].Status & JOB_STATUS_PRINTING)
           {
               /*
                *  If the job is in an error state,
                *  report an error for the printer.
                *  Code could be inserted here to
                *  attempt an interpretation of the
                *  pStatus member as well.
                */
               if (pJobs[i].Status &
                   (JOB_STATUS_ERROR |
                   JOB_STATUS_OFFLINE |
                   JOB_STATUS_PAPEROUT |
                   JOB_STATUS_BLOCKED_DEVQ))
               {
                   return TRUE;
               }
           }
       }

       /*
        *  No error condition
        */
       return FALSE;

   }

REFERENCES

For general instructions on calling Win32 Spooler functions, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q158828
   TITLE     : How To Call Win32 Spooler Enumeration APIs Properly