/////////////////////////////////////////////////////////////////////////////// 
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). 
// All rights reserved. 
// 
// This software and its documentation and related materials are owned by 
// the Alliance. The software may only be incorporated into application 
// programs owned by members of the Alliance, subject to a signed 
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable  
// trade secrets of the Alliance and its suppliers. The software is also 
// protected by copyright law and international treaty provisions. Application  
// programs incorporating this software must include the following statement 
// with their copyright notices:
//   
//   This application incorporates Open Design Alliance software pursuant to a license 
//   agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. 
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you 
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////


///////////////////////////////////////////////////////////////////////////////
//
// OdAttachedFile.h
//
///////////////////////////////////////////////////////////////////////////////

#ifndef _PDF_PUBLISH_ATTACHED_FILE_INCLUDED_
#define _PDF_PUBLISH_ATTACHED_FILE_INCLUDED_

#include "PdfPublishBaseObject.h"
#include "PdfPublishImage.h"
#include "StringArray.h"
#include "DoubleArray.h"

/** \details
  Contains declarations for Publish SDK.
  <group TD_Namespaces>
*/
namespace OdPdfPublish{

/** \details
   A class that implements storing and handling an attached file entity in PDF documents created with Publish SDK.
*/
class PDFPUBLISH_TOOLKIT OdAttachedFile : public OdObject
{
protected:
  OdAttachedFile();
  
public:
  ODRX_DECLARE_MEMBERS(OdAttachedFile);
  ODRX_HEAP_OPERATORS();

  /** \details
    Destroys an attached file object.
  */
  ~OdAttachedFile() override;

  /** \details
    Sets the displayed name of the attached file.
    Call the <link OdPdfPublish::OdObject::isValid@const, isValid()> method inherited from the <link OdPdfPublish::OdObject, OdObject> 
    class to check the status of the operation.

    \param name [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> that contains the new displayed name value.
  */
  void setName(const OdString& name);

  /** \details
    Sets the description of the attached file.

    \param description [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> that contains the new description.
  */
  void setDescription(const OdString& description);

  /** \details
    Sets the creation date of the attached file.

    \param creation_date [in] An <exref target="../tkernel_api_cpp/OdTimeStamp.html">OdTimeStamp</exref> object that represents the new creation date value.
  */
  void setCreationDate(const OdTimeStamp& creation_date);

  /** \details
    Sets the modification date of the attached file.

    \param mod_date [in] An <exref target="../tkernel_api_cpp/OdTimeStamp.html">OdTimeStamp</exref> object that represents the new modification date value.
  */
  void setModDate(const OdTimeStamp& mod_date);

  /** \details
    Sets the thumbnail <link OdPdfPublish::OdImage, image> of the attached file object.

    \param pImage [in] A smart pointer to a thumbnail <link OdPdfPublish::OdImage, raster image> object.
  */
  void setThumb(const OdImagePtr& pImage);

  /** \details
    Adds a text collection item for the attached file object.

    \param name [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> that represents the new name of the collection item value.
    \param item [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> that represents the new collection item value.
    \remarks
    * The name cannot contain any special characters or spaces. 
    * To display the item, the collection must contain a column with the same name.
  */
  void addTextCollectionItem(const OdString& name, const OdString& item);

  /** \details
    Adds a date collection item for the attached file.

    \param name [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> that represents the new name of the collection item value.
    \param date [in] An <exref target="../tkernel_api_cpp/OdTimeStamp.html">OdTimeStamp</exref> object that represents the new collection item value.
    \remarks
    * The name cannot contain any special characters or spaces. 
    * To display the item, the collection must contain a column with the same name.
  */
  void addDateCollectionItem(const OdString& name, const OdTimeStamp& date);

  /** \details
    Adds a number collection item for the attached file.

    \param name   [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> that represents the new name of the collection item value.
    \param number [in] A new collection item value.
    \remarks
    * The name cannot contain any special characters or spaces. 
    * To display the item, the collection must contain a column with the same name.
  */
  void addNumberCollectionItem(const OdString& name, const double& number);

  /** \details
    Sets the full filename of the attached file object.
    Call the <link OdPdfPublish::OdObject::isValid@const, isValid()> method inherited from the <link OdPdfPublish::OdObject, OdObject> 
    class to check the status of the operation.

    \param filename [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> that represents the new filename.
    \remarks
    The method also sets the displayed name of the file if it wasn't set previously.
  */
  void setFile(const OdString& filename);

  /** \details
    Sets the file stream buffer for the attached file object.
    Call the <link OdPdfPublish::OdObject::isValid@const, isValid()> method inherited from the <link OdPdfPublish::OdObject, OdObject> 
    class to check the status of the operation.
    
    \param file [in] A smart pointer to the stream buffer object.
    \remarks
    If the specified stream buffer object contains the displayed name of the file and it wasn't set previously, the method sets it.
  */
  void setFileStream(OdStreamBufPtr& file);

  /** \details
    Returns the current displayed name of the attached file.
    The method fills a passed <exref target="../tkernel_api_cpp/OdString.html">string</exref> object and returns it to the calling subroutine.

    \param name [out] A placeholder for the displayed name value.
  */
  void getName(OdString& name) const;

  /** \details
    Returns the current description of the attached file.
    The method fills a passed <exref target="../tkernel_api_cpp/OdString.html">string</exref> object and returns it to the calling subroutine.

    \param description [out] A placeholder for the description value.
  */
  void getDescription(OdString& description) const;

  /** \details
    Returns the current creation date of the attached file.
    The method fills a passed <exref target="../tkernel_api_cpp/OdTimeStamp.html">OdTimeStamp</exref> object and returns it to the calling subroutine.

    \param creation_date [out] A placeholder for the creation date value.
  */
  void getCreationDate(OdTimeStamp& creation_date) const;

  /** \details
    Returns the current modification date of the attached file.
    The method fills a passed <exref target="../tkernel_api_cpp/OdTimeStamp.html">OdTimeStamp</exref> object and returns it to the calling subroutine.

    \param mod_date [out] A placeholder for the modification date value.
  */
  void getModDate(OdTimeStamp& mod_date) const;

  /** \details
    Returns the current thumbnail <link OdPdfPublish::OdImage, raster image> of the attached file object.
    The method fills a passed <link OdPdfPublish::OdImage, raster image> object and returns it to the calling subroutine.

    \param pOutImage [out] A placeholder for the <link OdPdfPublish::OdImage, raster image> object.
  */
  void getThumb(OdImagePtr& pOutImage) const;

  /** \details
    Returns the text collection items of the attached file object.
    This method fills the passed <exref target="../tkernel_api_cpp/OdStringArray.html">string arrays</exref> and returns them to a calling subroutine.

    \param names [out] A placeholder for collection item names 
                       (an <exref target="../tkernel_api_cpp/OdStringArray.html">array</exref> of item names).
    \param items [out] A placeholder for collection item values (an <exref target="../tkernel_api_cpp/OdStringArray.html">array</exref> of item values).
  */
  void getTextCollectionItems(OdStringArray& names, OdStringArray& items) const;

  /** \details
    Returns the date collection items of the attached file object.
    This method fills the passed <exref target="../tkernel_api_cpp/OdStringArray.html">string array</exref> and 
    <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">array</exref> of 
    <exref target="../tkernel_api_cpp/OdTimeStamp.html">OdTimeStamp</exref> objects, then returns them to a calling subroutine.

    \param names [out] A placeholder for collection item names (an <exref target="../tkernel_api_cpp/OdStringArray.html">array</exref> of item names).
    \param dates [out] A placeholder for collection item values (an <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">array</exref> of item values).
  */
  void getDateCollectionItems(OdStringArray& names, OdArray<OdTimeStamp>& dates) const;

  /** \details
    Returns the number of collection items of the attached file object.
    This method fills the passed <exref target="../tkernel_api_cpp/OdStringArray.html">string array</exref> 
    and <exref target="../tkernel_api_cpp/OdDoubleArray.html">array of doubles</exref>, then returns them to a calling subroutine.

    \param names   [out] A placeholder for collection item names (an <exref target="../tkernel_api_cpp/OdStringArray.html">array</exref> of item names).
    \param numbers [out] A placeholder for number collection item values (an <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">array</exref> of item values).
  */
  void getNumberCollectionItems(OdStringArray& names, OdDoubleArray& numbers) const;

  /** \details
    Returns the full filename of the current <link OdPdfPublish::OdImage, image> of the attached file object.
    The method fills a passed <exref target="../tkernel_api_cpp/OdString.html">string</exref> object and returns it to the calling subroutine.

    \param out_filename [out] A placeholder for the full filename.
  */
  void getFile(OdString& out_filename) const;

  /** \details 
    Returns the current <exref target="../tkernel_api_cpp/OdStreamBuf.html">OdStreamBuf</exref> object associated with the attached file object.
    The method fills a passed <exref target="../tkernel_api_cpp/OdStreamBuf.html">OdStreamBuf</exref> object and returns it to the calling subroutine.
   
    \param file [out] A placeholder for the <exref target="../tkernel_api_cpp/OdStreamBuf.html">OdStreamBuf</exref> object.
  */ 
  void getFileStream(OdStreamBufPtr& file) const;

};

/** \details
  A data type that represents a smart pointer to an <link OdPdfPublish::OdAttachedFile, OdAttachedFile> object.
*/
SMARTPTR(OdAttachedFile);

}
#endif // _PDF_PUBLISH_ATTACHED_FILE_INCLUDED_