Class: TPrintJobHandle

Declaration: PrintJobHandle.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

Acts as a handle or pointer to a previously submitted print job. Queries to the handle provide the print job status and other information about the job as it progresses through printing. It is also possible to change the disposition of the job if something goes awry or the clients see fit to change it. The job can be canceled, rerouted to a different printer, deferred to a later time, deferred indefinitely, or undeferred. It must be emphasized, however, that clients are not required to manage submitted jobs with a print job handle; this object is provided solely as a convenience for the client. Users interact with printed jobs through other means. To obtain a print job handle to a particular print job, the client asks the print channel to create one at the same time that EndJob is called. However, instead of calling EndJob, the client calls EndJobAndCreateJobHandle which returns a TPrintJobHandle for the job just submitted. That object reflects the state of that job until the job is fully printed or becomes unknown to the system. After the client is finished with the handle, the client can delete it at any time whether the job is completed or not.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Although clients are not normally expected to derive from this class, derivations are allowed for print jobs that are both created and handled by other systems or frameworks not specifically handled by printing. Clients normally get job handles on request when submitting a job through regular printing channels. If you derive from this class, there is no guarantee that your class can be used in the regular printing subsystems to track any actual print job since clients do not normally create print job handles. They are provided to you on request by the printing subsystem. If you do derive from this class, clients should override Set and Get name to allow naming of the job. CLients should also override DeleteJob to allow a job to be deleted or aborted before it has completed its normal processing. IsValid should be overridden to signify the validity of the job when queried. CancelPrinting, DeferPrinting, DeferPrintingUntil, UndeferPrinting, and MoveTo should be overridden to change the processing status of the job at any point. GetJobStatus need be overridden only if this information is important to clients of your derived class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPrintJobHandle::~TPrintJobHandle

virtual ~ TPrintJobHandle ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::SetName

virtual void SetName (const TStandardText & name)

Interface Category:

API.

Purpose:

Sets the name for this print job. This is the name by which the job is listed in the printers job queue.

Calling Context:

Called directly and by the printing system (MBasePrintChannel derived classes) to set the name of the print job.

Parameters:

const TStandardText & name -The name to set to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::GetName

virtual void GetName (TStandardText & name)

Interface Category:

API.

Purpose:

Returns the name of this print job.

Calling Context:

Called by clients to get the name of this print job.

Parameters:

TStandardText & name -The object to fill in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TPrintJobHandle::DeleteJob

virtual void DeleteJob ()

Interface Category:

API.

Purpose:

Deletes the job and removes it from the printers queue.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::IsValid

virtual bool IsValid () const

Interface Category:

API.

Purpose:

Checks whether the object represents a valid existing print job.

Calling Context:

Mostly called by other functions of the object.

Parameters:

Takes no parameters.

Return Value:

Returns true if there is a valid persistent store representing this job.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::CancelPrinting

virtual void CancelPrinting ()

Interface Category:

API.

Purpose:

Cancels printing for this job. Leaves the job in the printers queue. The job can be removed manually or reprinted at a later time.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::DeferPrinting

virtual void DeferPrinting ()

Interface Category:

API.

Purpose:

Defers processing of this job. Pauses this job.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::DeferPrintingUntil

virtual void DeferPrintingUntil (const TTime & when)

Interface Category:

API.

Purpose:

Defers printing until the time specified.

Calling Context:

Call this function directly.

Parameters:

const TTime & when -Pauses the job until this time.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::UndeferPrinting

virtual void UndeferPrinting ()

Interface Category:

API.

Purpose:

Resumes printing the job.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::MoveTo

virtual void MoveTo (TPrinter &)

Interface Category:

API.

Purpose:

Moves the job to another printer. Deletes it from the current printer's queue.

Calling Context:

Call this function directly.

Parameters:

TPrinter & -The printer the job is to move to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::GetJobStatus

virtual void GetJobStatus (TPrintJobStatus & status) const

Interface Category:

API.

Purpose:

Returns the status of the job.

Calling Context:

Call this function directly.

Parameters:

TPrintJobStatus & status -Where the status is returned.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::operator=

TPrintJobHandle & operator =(const TPrintJobHandle & job)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPrintJobHandle & job -The object to be copied.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream the object is streamed in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::operator>>=

virtual TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -The object the object is streamed out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called to generate a hash value.

Parameters:

Takes no parameters.

Return Value:

A long value representing the hash value of the object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrintJobHandle::TPrintJobHandle

TPrintJobHandle ()
TPrintJobHandle (const TPrintJobHandle & job)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and derived classes.
Called to copy an object. Also called by derived classes.

Parameters:

Takes no parameters.
const TPrintJobHandle & job -The object to copy from.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.