/********************************************************************
 * Job Ticket API (JTAPI) fsgjt_job_ticket_info.h
 *  
 * Copyright (c) 2004 High North Inc.
 * Copyright (c) 2004 International Business Machines Corp.
 * Copyright (c) 2004 Seiko-Epson, Inc.
 * Copyright (c) 2004 Till Kamppeter.  
 * Copyright (c) 2004 Free Standards Group.                   
 *                                                                    
 *                    Common Public License - v 1.0 
 * THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS 
 * COMMON PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR 
 * DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE 
 * OF THIS AGREEMENT.   
 *
 * The Common Public License in its entirety is located in 
 * fsgjt_cpl.h and applies to the contents of this file. 
 *******************************************************************/

#ifndef FSGJT_JOB_TICKET_INFO_H
#define FSGJT_JOB_TICKET_INFO_H

#include <stdio.h>
#include <fsgjt.h>

/* Defined constant to uniquely identify this type of JTAPI object */
#define FSGJT_JOB_TICKET_INFO_OBJECT    "JTIC"

/************************************************************
 * Job Ticket Info attributes
 ***********************************************************/
/* Single value where type is fsgjt_charset_t (Charset) */
#define FSGJT_JT_API_CHARSET                 "jt-api-charset"

/* Single value where type is fsgjt_text_t (Text) */
#define FSGJT_JT_API_VERSION                 "jt-api-version"

/* Single value where type is fsgjt_text_t (Text) */
#define FSGJT_JT_AUTHOR_NAME                 "jt-author-name"

/* Single value where type is fsgjt_charset_t (Charset) */
#define FSGJT_JT_CHARSET                     "jt-charset"

/* Single value where type is fsgjt_text_t (Text) */
#define FSGJT_JT_COMMENT                     "jt-comment"

/* Single value where type is fsgjt_present_t (PresentEnum) */
#define FSGJT_JT_FIDELITY                    "jt-fidelity"

/* Single value where type is fsgjt_object_t (Job) */
#define FSGJT_JT_JOB                         "jt-job"

/* Single value where type is fsgjt_length_unit_t */
/* (LengthUnitEnum) */
#define FSGJT_JT_LENGTH_UNIT                 "jt-length-unit"

/* Single value where type is fsgjt_job_ticket_type_version_t */
/* (JobTicketTypeVersionEnum) */
#define FSGJT_JT_TYPE_AND_VERSION            "jt-type-and-version"

/* Single value where type is fsgjt_text_t (Text) */
#define FSGJT_JT_VERSION                     "jt-version"

/************************************************************
 * fsgjtNewJobTicketInfo - Creates a JobTicketInfo object.
 * Used when a new JobTicketInfo is being created without
 * a Job object and not from an external job ticket.
 *
 * param (output) fsgjt_object_t* jobTicketInfo - Pointer to 
 *      the new JobTicketInfo to create
 * param (input) fsgjt_job_ticket_type_version_t
 *      typeAndVersion - Type and version of this Job Ticket
 *      (use JobTicketTypeVersionEnum)
 *
 * return fsgjt_return_code_t
 ***********************************************************/
fsgjt_return_code_t fsgjtNewJobTicketInfo(
               fsgjt_object_t* jobTicketInfo,
               fsgjt_job_ticket_type_version_t typeAndVersion);

/************************************************************
 * fsgjtNewJobTicketInfoFromURI - Creates a JobTicketInfo 
 * object from the job ticket file at the provided URI. Other 
 * JTAPI objects are also created based on the information in
 * the job ticket file.
 *
 * param (output) fsgjt_object_t* jobTicketInfo - Pointer to 
 *      the JobTicketInfo to create
 * param (input) fsgjt_uri_t uri - URI where job ticket file 
 *      resides
 * param (input) fsgjt_job_ticket_type_version_t
 *      typeAndVersion - Type and version of this Job Ticket
 *      (use JobTicketTypeVersionEnum)
 *
 * return fsgjt_status_t
 ***********************************************************/
fsgjt_status_t fsgjtNewJobTicketInfoFromURI(
               fsgjt_object_t* jobTicketInfo,
               fsgjt_uri_t uri,
               fsgjt_job_ticket_type_version_t typeAndVersion);

/************************************************************
 * fsgjtNewJobTicketInfoFromBuffer - Creates a JobTicketInfo 
 * object from the provided buffer that contains a job 
 * ticket. Other JTAPI objects are also created based on the 
 * information in the job ticket buffer.
 *
 * param (output) fsgjt_object_t* jobTicketInfo - Pointer to 
 *      the JobTicketInfo to create
 * param (input) fsgjt_text_t buffer - Buffer that contains
 *      the job ticket
 * param (input) fsgjt_int32_t bufferSize - Size of the input
 *      buffer
 * param (input) fsgjt_job_ticket_type_version_t
 *      typeAndVersion - Type and version of this Job Ticket
 *      (use JobTicketTypeVersionEnum)
 *
 * return fsgjt_status_t
 ***********************************************************/
fsgjt_status_t fsgjtNewJobTicketInfoFromBuffer(
               fsgjt_object_t* jobTicketInfo,
               fsgjt_text_t buffer,
               fsgjt_int32_t bufferSize,
               fsgjt_job_ticket_type_version_t typeAndVersion);

/************************************************************
 * fsgjtNewJobTicketInfoFromJob - Creates a JobTicketInfo 
 * object using the provided Job object. Used when a new job 
 * ticket is being created. The Job object must be created 
 * first.
 *
 * param (output) fsgjt_object_t* jobTicketInfo - Pointer to 
 *      the new JobTicketInfo to create
 * param (input) fsgjt_object_t job - Job object that this 
 *      JobTicketInfo is to contain
 * param (input) fsgjt_job_ticket_type_version_t
 *      typeAndVersion - Type and version of this Job Ticket
 *      (use JobTicketTypeVersionEnum)
 *
 * return fsgjt_return_code_t
 ***********************************************************/
fsgjt_return_code_t fsgjtNewJobTicketInfoFromJob(
               fsgjt_object_t* jobTicketInfo,
               fsgjt_object_t job,
               fsgjt_job_ticket_type_version_t typeAndVersion);

/************************************************************
 * fsgjtWriteJobTicketToBuffer - Writes a job ticket to the 
 * provided buffer.  The caller should pass a _large_ buffer
 * to avoid failure due to buffer overrun.  The caller may
 * then use C standard 'realloc()' to 'trim' the buffer.
 *
 * param (input) fsgjt_object_t jobTicketInfo - JobTicketInfo 
 *      from which the job ticket is to be written
 * param (output) fsgjt_text_t buffer - Buffer to write the
 *      job ticket to.  The buffer must be created by the
 *      caller.
 * param (input/output) fsgjt_int32_t* bufferSize - Size of
 *      buffer that the caller created and the returned size
 *      of the data written to the buffer (i.e., length of
 *      the serialized job ticket) for 'trimming'.
 *
 * return fsgjt_return_code_t
 ***********************************************************/
fsgjt_return_code_t fsgjtWriteJobTicketToBuffer(
               fsgjt_object_t jobTicketInfo,
               fsgjt_text_t buffer,
               fsgjt_int32_t* bufferSize);

/************************************************************
 * fsgjtWriteJobTicketToURI - Writes a job ticket at the
 * provided URI.
 *
 * param (input) fsgjt_object_t jobTicketInfo - JobTicketInfo  
 *      from which the job ticket is to be written
 * param (output) fsgjt_uri_t uri - URI of the job ticket 
 *      that is to be created from the JobTicketInfo. 
 *
 * return fsgjt_return_code_t
 ***********************************************************/
fsgjt_return_code_t fsgjtWriteJobTicketToURI(
               fsgjt_object_t jobTicketInfo,
               fsgjt_uri_t uri);

#endif /* FSGJT_JOB_TICKET_INFO_H */