EnumJobs Function

Declare Function EnumJobs Lib "winspool.drv" Alias "EnumJobsA" (ByVal hPrinter As Long, ByVal FirstJob As Long, ByVal NoJobs As Long, ByVal Level As Long, pJob As Long, ByVal cbBuf As Long, pcbNeeded As Long, pcReturned As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

EnumJobs enumerates all of the print jobs pending for a given printer. The function can retrieve either (relatively) brief or detailed information describing each job in the print queue for that printer. Note that, instead of placing the information directly into the corresponding structures, the function places the information into an array. The array's contents must then be transfered to one or more structures. In order to determine how much space is necessary to receive the information about each print job, first call the function with cbBuf set to 0. The function will set the variable passed as pcbNeeded to the size in bytes of the array necessary hold the information.

Return Value

If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non-zero value.

Visual Basic-Specific Issues

The data retrieved by the function cannot be directly copied into structure(s) using CopyMemory or some other method. Instead, each (desired) member of the structure must manually be copied from the array to the structure, using the corresponding array indices. Each structure's contents appear sequentially in the array, and one structure immediately follows another. See the example code for a demonstration on how this is done.

Additionally, strings are not stored directly. Instead, the data placed into the array contains pointers to strings whenever necessary. The string manipulation API functions lstrlen and lstrcpy are needed to copy the pointed-to string into the structure's string data member(s). Again, see the example for a clearer demonstration. However, to copy structures stored under the original structure, CopyMemory can be used. Of course, numeric data members can be copied directly from the array to the structure.

Finally, when determining the space needed for the array, both pJob and cbBuf must be set to 0. To set pJob to 0, the expression ByVal 0 must be used.

Parameters

hPrinter: A handle to the printer to enumerate the print jobs of.
FirstJob: The zero-baded position in the print queue to begin print job enumeration from. To enumerate all jobs, of course set this to 0. To enumerate everything except the first job, set this to 1 (identifying the second print job), etc.
NoJobs: The maximum number of print jobs to enumerate.
Level: Identifies the format of the information placed into the array passed as pJob. If this is 1, the data is in the format of JOB_INFO_1 structures. If this is 2, the data is in the format of JOB_INFO_2 structures.
pJob: An array which receives all the information about the print jobs retrieved by the function. The format of this data is specified in Level. The array must be large enough to receive all the data. If you are setting cbBuf to 0, this must also be 0.
cbBuf: The size in bytes of the array passed as pJob. To determine how large the array must be, set this to 0.
pcbNeeded: Receives the number of bytes of data copied into the array passed as pJob. If the function failed, this is the minimum size in bytes which the array passed as pJob must be.
pcReturned: Receives the number of print jobs retrieved by the function.

Example

' This code is licensed according to the terms and conditions listed here.

' Display a little information about each print job in the
' queue for the default printer.  Note how both EnumPrinters and
' EnumJobs first copy the data into the arrays before placing
' the information into the desired structure.
Dim pi1 As PRINTER_INFO_1  ' holds a little information about the printer
Dim hPrinter As Long  ' handle to the default printer once it is opened
Dim arraybuf() As Long  ' resizable array used as a buffer
Dim jobinfo As JOB_INFO_2  ' holds detailed info about a print job
Dim needed As Long  ' receives space needed in the buffer array
Dim numitems As Long  ' receives the number of items returned
Dim lendivfour As Long  ' the size in Long-type units of the jobinfo structure
Dim c As Long  ' counter variable
Dim retval As Long  ' return value

' -- Get the name of the default printer. --
' Determine how much space is needed to get the printer information.
retval = EnumPrinters(PRINTER_ENUM_DEFAULT, "", 1, ByVal 0, 0, needed, numitems)
' Resize the array buffer to the needed size in bytes.
ReDim arraybuf(0 To needed / 4 - 1)  ' remember each element is 4 bytes
' Retrieve the information about the default printer.
retval = EnumPrinters(PRINTER_ENUM_DEFAULT, "", 1, arraybuf(0), needed, needed, numitems)
' Copy the printer name into the structure.  The rest is unnecessary.
pi1.pName = Space(lstrlen(arraybuf(2)))
retval = lstrcpy(pi1.pName, arraybuf(2))

' -- Obtain a handle to the default printer (using default configuration). --
retval = OpenPrinter(pi1.pName, hPrinter, ByVal CLng(0))

' -- Enumerate the default printer's print jobs currently queued. --
' Determine how much space is needed to get the print jobs' information.
retval = EnumJobs(hPrinter, 0, 100, 2, ByVal 0, 0, needed, numitems)
' Resize the array buffer to the needed size in bytes.
ReDim arraybuf(0 To needed / 4 - 1)  ' remember each element is 4 bytes
' Retrieve the information about the print jobs.
retval = EnumJobs(hPrinter, 0, 100, 2, arraybuf(0), needed, needed, numitems)
' Display the number of print jobs currently in the queue.
If numitems > 0 Then
  Debug.Print "There are"; numitems; "print jobs currently in the queue."
Else
  Debug.Print "No print jobs are currently in the queue."
End If

' For each print job, copy its data into the structure.  Then display selected
' information from the structure.  For brevity, this example copies only a
' few of the data members into the structure.
lendivfour = Len(jobinfo) / 4  ' this is the number of elements for each structure in the array
For c = 0 To numitems - 1  ' loop through each item
  ' Copy selected information into the structure: the job ID number, the
  ' name of the user who printed it, the total number of pages, and
  ' the time it was added into the queue.
  jobinfo.JobID = arraybuf(lendivfour * c)  ' the first element of the array chunk
  jobinfo.pUserName = Space(lstrlen(arraybuf(lendivfour * c + 3)))  ' fourth element
  retval = lstrcpy(jobinfo.pUserName, arraybuf(lendivfour * c + 3))
  jobinfo.TotalPages = arraybuf(lendivfour * c + 18)  ' nineteenth element
  CopyMemory jobinfo.Submitted, arraybuf(lendivfour * c + 20), Len(jobinfo.Submitted)  ' twenty-first element
  
  ' Display the copied information.
  Debug.Print "Job ID number:"; jobinfo.JobID
  Debug.Print "Printed by user: "; jobinfo.pUserName
  Debug.Print "Number of pages:"; jobinfo.TotalPages
  Debug.Print "Placed in queue on: ";
  ' (display the date and time stored in jobinfo.Submitted)
  Debug.Print jobinfo.Submitted.wMonth; "-"; jobinfo.Submitted.wDay; "-"; jobinfo.Submitted.wYear; " ";
  Debug.Print jobinfo.Submitted.wHour; ":"; jobinfo.Submitted.wMinute; ":"; jobinfo.Submitted.wSecond; " GMT"
Next c

' Close the printer handle now that it is no longer needed.
retval = ClosePrinter(hPrinter)