Share via

How to: Discover Whether a Print Job Can Be Printed At This Time of Day

  • Article

Print queues are not always available for 24 hours a day. They have start and end time properties that can be set to make them unavailable at certain times of day. This feature can be used, for example, to reserve a printer for the exclusive use of a certain department after 5 pm. That department would have a different queue servicing the printer than other departments use. The queue for the other departments would be set to be unavailable after 5 pm, while queue for the favored department could be set to be available at all times.

Moreover, print jobs themselves can be set to be printable only within a specified span of time.

The PrintQueue and PrintSystemJobInfo classes exposed in the APIs of Microsoft .NET Framework version 3.0 provide a means for remotely checking whether a given print job can print on a given queue at the current time.

Example

The example below is taken from a sample application that can diagnose problems with a print job. For the full sample, see Diagnose Problematic Print Job Sample.

There are two major steps for this kind of function as follows.

  1. Read the StartTimeOfDay and UntilTimeOfDay properties of the PrintQueue to determine whether the current time is between them.

  2. Read the StartTimeOfDay and UntilTimeOfDay properties of the PrintSystemJobInfo to determine whether the current time is between them.

But complications arise from the fact that these properties are not DateTime objects. Instead they are Int32 objects that express the time of day as the number of minutes since midnight. Moreover, this is not midnight in the current time zone, but midnight UTC (Coordinated Universal Time).

The first code example presents the static method ReportQueueAndJobAvailability, which is passed a PrintSystemJobInfo and calls helper methods to determine whether the job can print at the current time and, if not, when it can print. Notice that a PrintQueue is not passed to the method. This is because the PrintSystemJobInfo includes a reference to the queue in its HostingPrintQueue property.

The subordinate methods include the overloaded ReportAvailabilityAtThisTime method which can take either a PrintQueue or a PrintSystemJobInfo as a parameter. There is also a TimeConverter.ConvertToLocalHumanReadableTime. All of these methods are discussed below.

The ReportQueueAndJobAvailability method begins by checking to see if either the queue or the print job is unavailable at this time. If either of them is unavailable, it then checks to see if the queue unavailable. If it is not available, then the method reports this fact and the time when the queue will become available again. It then checks the job and if it is unavailable, it reports the next time span when it when it can print. Finally, the method reports the earliest time when the job can print. This is the later of following two times.

  • The time when the print queue is next available.

  • The time when the print job is next available.

When reporting times of day, the ToShortTimeString method is also called because this method suppresses the years, months, and days from the output. You cannot restrict the availability of either a print queue or a print job to particular years, months, or days.

static void ReportQueueAndJobAvailability (PrintSystemJobInfo^ theJob) 
{
   if (!(ReportAvailabilityAtThisTime(theJob->HostingPrintQueue) && ReportAvailabilityAtThisTime(theJob)))
   {
      if (!ReportAvailabilityAtThisTime(theJob->HostingPrintQueue))
      {
         Console::WriteLine("\nThat queue is not available at this time of day." + "\nJobs in the queue will start printing again at {0}", TimeConverter::ConvertToLocalHumanReadableTime(theJob->HostingPrintQueue->StartTimeOfDay).ToShortTimeString());
         // TimeConverter class is defined in the complete sample
      }
      if (!ReportAvailabilityAtThisTime(theJob))
      {
         Console::WriteLine("\nThat job is set to print only between {0} and {1}", TimeConverter::ConvertToLocalHumanReadableTime(theJob->StartTimeOfDay).ToShortTimeString(), TimeConverter::ConvertToLocalHumanReadableTime(theJob->UntilTimeOfDay).ToShortTimeString());
      }
      Console::WriteLine("\nThe job will begin printing as soon as it reaches the top of the queue after:");
      if (theJob->StartTimeOfDay > theJob->HostingPrintQueue->StartTimeOfDay)
      {
         Console::WriteLine(TimeConverter::ConvertToLocalHumanReadableTime(theJob->StartTimeOfDay).ToShortTimeString());
      } else
      {
         Console::WriteLine(TimeConverter::ConvertToLocalHumanReadableTime(theJob->HostingPrintQueue->StartTimeOfDay).ToShortTimeString());
      }

   }
};

internal static void ReportQueueAndJobAvailability(PrintSystemJobInfo theJob)
{
    if (!(ReportAvailabilityAtThisTime(theJob.HostingPrintQueue) && ReportAvailabilityAtThisTime(theJob)))
    {
        if (!ReportAvailabilityAtThisTime(theJob.HostingPrintQueue))
        {
            Console.WriteLine("\nThat queue is not available at this time of day." +
                "\nJobs in the queue will start printing again at {0}",
                 TimeConverter.ConvertToLocalHumanReadableTime(theJob.HostingPrintQueue.StartTimeOfDay).ToShortTimeString());
            // TimeConverter class is defined in the complete sample
        }

        if (!ReportAvailabilityAtThisTime(theJob))
        {
            Console.WriteLine("\nThat job is set to print only between {0} and {1}",
                TimeConverter.ConvertToLocalHumanReadableTime(theJob.StartTimeOfDay).ToShortTimeString(),
                TimeConverter.ConvertToLocalHumanReadableTime(theJob.UntilTimeOfDay).ToShortTimeString());
        }
        Console.WriteLine("\nThe job will begin printing as soon as it reaches the top of the queue after:");
        if (theJob.StartTimeOfDay > theJob.HostingPrintQueue.StartTimeOfDay)
        {
            Console.WriteLine(TimeConverter.ConvertToLocalHumanReadableTime(theJob.StartTimeOfDay).ToShortTimeString());
        }
        else
        {
            Console.WriteLine(TimeConverter.ConvertToLocalHumanReadableTime(theJob.HostingPrintQueue.StartTimeOfDay).ToShortTimeString());
        }

    }//end if at least one is not available

}//end ReportQueueAndJobAvailability

The two overloads of the ReportAvailabilityAtThisTime method are identical except for the type passed to them, so only the PrintQueue version is presented below. (For the full sample, see Diagnose Problematic Print Job Sample.)

NoteNote:

The fact that the methods are identical except for type raises the question of why the sample does not create a generic method ReportAvailabilityAtThisTime<T>. The reason is that such a method would have to be restricted to a class that has the StartTimeOfDay and UntilTimeOfDay properties that the method calls, but a generic method can only be restricted to a single class and the only class common to both PrintQueue and PrintSystemJobInfo in the inheritance tree is PrintSystemObject which has no such properties.

The ReportAvailabilityAtThisTime method (presented in the code example below) begins by initializing a Boolean sentinel variable to true. It will be reset to false, if the queue is not available.

Next, the method checks to see if the start and "until" times are identical. If they are, the queue is always available, so the method returns true.

If the queue is not available all the time, the method uses the static UtcNow property to get the current time as a DateTime object. (We do not need local time because the StartTimeOfDay and UntilTimeOfDay properties are themselves in UTC time.)

However, these two properties are not DateTime objects. They are Int32s expressing the time as the number of minutes-after-UTC-midnight. So we do have to convert our DateTime object to minutes-after-midnight. When that is done, the method simply checks to see whether "now" is between the queue's start and "until" times, sets the sentinel to false if "now" is not between the two times, and returns the sentinel.

static Boolean ReportAvailabilityAtThisTime (PrintQueue^ pq) 
{
   Boolean available = true;
   if (pq->StartTimeOfDay != pq->UntilTimeOfDay)
   {
      DateTime utcNow = DateTime::UtcNow;
      Int32 utcNowAsMinutesAfterMidnight = (utcNow.TimeOfDay.Hours * 60) + utcNow.TimeOfDay.Minutes;

      // If now is not within the range of available times . . .
      if (!((pq->StartTimeOfDay < utcNowAsMinutesAfterMidnight) && (utcNowAsMinutesAfterMidnight < pq->UntilTimeOfDay)))
      {
         available = false;
      }
   }
   return available;
};

private static Boolean ReportAvailabilityAtThisTime(PrintQueue pq)
{
    Boolean available = true;
    if (pq.StartTimeOfDay != pq.UntilTimeOfDay) // If the printer is not available 24 hours a day
    {
        DateTime utcNow = DateTime.UtcNow;
        Int32 utcNowAsMinutesAfterMidnight = (utcNow.TimeOfDay.Hours * 60) + utcNow.TimeOfDay.Minutes;

        // If now is not within the range of available times . . .
        if (!((pq.StartTimeOfDay < utcNowAsMinutesAfterMidnight) 
           && 
           (utcNowAsMinutesAfterMidnight < pq.UntilTimeOfDay)))
        {
            available = false;
        }
    }
    return available;
}//end ReportAvailabilityAtThisTime

The TimeConverter.ConvertToLocalHumanReadableTime method (presented in the code example below) does not use any methods introduced with Microsoft .NET Framework version 3.0, so the discussion is brief. The method has a double conversion task: it must take an integer expressing minutes-after-midnight and convert it to a human-readable time and it must convert this to the local time. It accomplishes this by first creating a DateTime object that is set to midnight UTC and then it uses the AddMinutes method to add the minutes that were passed to the method. This returns a new DateTime expressing the original time that was passed to the method. The ToLocalTime method then converts this to local time.

private ref class TimeConverter {

internal: 
   static DateTime ConvertToLocalHumanReadableTime (Int32 timeInMinutesAfterUTCMidnight) 
   {
      // Construct a UTC midnight object.
      // Must start with current date so that the local Daylight Savings system, if any, will be taken into account.
      DateTime utcNow = DateTime::UtcNow;
      DateTime utcMidnight = DateTime(utcNow.Year, utcNow.Month, utcNow.Day, 0, 0, 0, DateTimeKind::Utc);

      // Add the minutes passed into the method in order to get the intended UTC time.
      Double minutesAfterUTCMidnight = ((Double)timeInMinutesAfterUTCMidnight);
      DateTime utcTime = utcMidnight.AddMinutes(minutesAfterUTCMidnight);

      // Convert to local time.
      DateTime localTime = utcTime.ToLocalTime();

      return localTime;
   };
};

class TimeConverter
{
    // Convert time as minutes past UTC midnight into human readable time in local time zone.
    internal static DateTime ConvertToLocalHumanReadableTime(Int32 timeInMinutesAfterUTCMidnight)
    {
        // Construct a UTC midnight object.
        // Must start with current date so that the local Daylight Savings system, if any, will be taken into account.
        DateTime utcNow = DateTime.UtcNow; 
        DateTime utcMidnight = new DateTime(utcNow.Year, utcNow.Month, utcNow.Day, 0, 0, 0, DateTimeKind.Utc);
        
        // Add the minutes passed into the method in order to get the intended UTC time.
        Double minutesAfterUTCMidnight = (Double)timeInMinutesAfterUTCMidnight;
        DateTime utcTime = utcMidnight.AddMinutes(minutesAfterUTCMidnight);
        
        // Convert to local time.
        DateTime localTime = utcTime.ToLocalTime();

        return localTime;

    }// end ConvertToLocalHumanReadableTime

}//end TimeConverter class

See Also

Reference

DateTime
PrintSystemJobInfo
PrintQueue

Concepts

Documents in Windows Presentation Foundation
Printing Overview

Other Resources

Printing Samples