/********************************************************************
 * Job Ticket API (JTAPI) fsgjt_attribute.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_ATTRIBUTE_H
#define FSGJT_ATTRIBUTE_H

#include <fsgjt.h>
#include <fsgjt_enums.h>

/************************************************************
 * fsgjtNewAttribute - Creates a new Attribute object having 
 * the provided attribute name, value type, and value.
 *
 * param (output) fsgjt_attribute_t* attribute - Pointer to
 *      the new Attribute returned.
 * param (input) fsgjt_text_t name - Name for the new
 *      Attribute to create
 * param (input) fsgjt_text_t type - Type for the new
 *      Attribute to create (use Value Types)
 * param (input) void* value - Pointer to the value for this 
 *      attribute.  Multiple values should be added with the
 *      fsgjtAddValue() function.
 *
 * return fsgjt_return_code_t
 ************************************************************/
fsgjt_return_code_t fsgjtNewAttribute(
               fsgjt_attribute_t* attribute, 
               fsgjt_text_t name, 
               fsgjt_text_t type, 
               void* value);

/************************************************************
 * fsgjtDestroyAttribute - Free the memory used by the 
 * Attribute.
 *
 * param (input) fsgjt_attribute_t attribute - Attribute to 
 *      free
 *
 * return fsgjt_return_code_t
 ************************************************************/
fsgjt_return_code_t fsgjtDestroyAttribute(
               fsgjt_attribute_t attribute);

/************************************************************
 * fsgjtAddValue - Add an additional value to this Attribute.
 *
 * param (input) fsgjt_attribute_t attribute - Attribute to
 *      add the provided value to 
 * param (input) void* value - Pointer to value to add
 *
 * return fsgjt_return_code_t 
 ************************************************************/
fsgjt_return_code_t fsgjtAddValue(
               fsgjt_attribute_t attribute, 
               void* value);

/************************************************************
 * fsgjtGetName - Get the name of the Attribute.
 *
 * param (input) fsgjt_attribute_t attribute - Attribute 
 *      whose name to get
 * param (output) fsgjt_text_t* name - Name of the
 *      Attribute
 *
 * return fsgjt_return_code_t
 ************************************************************/
fsgjt_return_code_t fsgjtGetName(
               fsgjt_attribute_t attribute,
               fsgjt_text_t* name);

/************************************************************
 * fsgjtGetNextValue - Return the Attribute's next value.
 *
 * param (input) fsgjt_attribute_t attribute - Attribute 
 *       whose next value is to be returned
 * param (output) void** nextValue - Pointer to the next 
 *       value
 * param (output) fsgjt_present_t* moreValues - On if there
 *       are more values for the Attribute other than the
 *       value being returned 
 *
 * return fsgjt_return_code_t 
 ************************************************************/
fsgjt_return_code_t fsgjtGetNextValue(
               fsgjt_attribute_t attribute,
               void** nextValue,
               fsgjt_present_t* moreValues);

/************************************************************
 * fsgjtGetNumValues - Get the number of values that the
 * Attribute contains.
 *
 * param (input) fsgjt_attribute_t attribute - Attribute 
 *      whose number of values to get
 * param (output) fsgjt_int32_t* numValues - Number of 
 *      values
 *
 * return fsgjt_return_code_t
 ************************************************************/
fsgjt_return_code_t fsgjtGetNumValues(
               fsgjt_attribute_t attribute,
               fsgjt_int32_t* numValues);

/************************************************************
 * fsgjtGetValueType - Returns the type of the Attribute's 
 * values.
 *
 * param (input) fsgjt_attribute_t attribute - Attribute 
 *       whose value type to get
 * param (output) fsgjt_text_t* type - Type of this
 *       Attribute's values (use Value Types)
 *
 * return fsgjt_return_code_t
 ************************************************************/
fsgjt_return_code_t fsgjtGetValueType(
               fsgjt_attribute_t attribute,
               fsgjt_text_t* type);

/************************************************************
 * fsgjtReplaceValue - Replaces the existing values for this
 * Attribute with the provided value.
 * 
 * param (input) fsgjt_attribute_t attribute - Attribute to
 *      replace the existing values
 * param (input) void* value - Pointer to replacement value
 *
 * return fsgjt_return_code_t 
 ************************************************************/
fsgjt_return_code_t fsgjtReplaceValue(
               fsgjt_attribute_t attribute, 
               void* value);

/************************************************************
 * fsgjtResetToFirstValue - Reset the iterator to point to
 * the first value of the Attribute.
 *
 * param (input) fsgjt_attribute_t attribute - Attribute 
 *      to reset
 *
 * return fsgjt_return_code_t
 ************************************************************/
fsgjt_return_code_t fsgjtResetToFirstValue(
               fsgjt_attribute_t attribute);

#endif /* FSGJT_ATTRIBUTE_H */