/*---------------------------------------------------------------------------*
 |           pCOS - PDF Information Retrieval Tool                           |
 +---------------------------------------------------------------------------+
 |         Copyright (c) 2007 PDFlib GmbH. All rights reserved.              |
 *---------------------------------------------------------------------------*
 |          Proprietary source code -- do not redistribute!                  |
 *---------------------------------------------------------------------------*/

/* $Id: pcoslib.h,v 1.19.2.2 2007/10/22 20:32:20 rjs Exp $
 *
 * pCOS public function declarations
 *
 */

/*
 * ----------------------------------------------------------------------
 * Setup, mostly Windows calling conventions and DLL stuff
 * ----------------------------------------------------------------------
 */

#ifndef PCOSLIB_H
#define PCOSLIB_H

#include <stdio.h>

#ifdef WIN32

#if !defined(PDFLIB_CALL)
#define PDFLIB_CALL     __cdecl
#endif

#if !defined(PDFLIB_API)
#ifdef PDFLIB_EXPORTS
#define PDFLIB_API __declspec(dllexport) /* prepare a DLL (internal use only) */

#elif defined(PDFLIB_DLL)
#define PDFLIB_API __declspec(dllimport) /* library clients: import DLL */

#else   /* !PDFLIB_DLL */
#define PDFLIB_API /* */        /* default: generate or use static library */

#endif  /* !PDFLIB_DLL */
#endif /* !PDFLIB_API */

#else   /* !WIN32 */

#if ((defined __IBMC__ || defined __IBMCPP__) && defined __DLL__ && defined OS2)
    #define PDFLIB_CALL _Export
    #define PDFLIB_API
#endif  /* IBM VisualAge C++ DLL */

#ifndef PDFLIB_CALL
#define PDFLIB_CALL
#endif
#ifndef PDFLIB_API
#define PDFLIB_API
#endif

#endif  /* !WIN32 */

/* export all symbols for a shared library on the Mac */
#if defined(__MWERKS__) && defined(PDFLIB_EXPORTS)
#pragma export on
#endif

/* Make our declarations C++ compatible */
#ifdef __cplusplus
extern "C" {
#endif

#define PCOS_PRODUCTNAME         "pCOS"
#define PCOS_PRODUCTDESCR        "PDF Information Retrieval Tool"
#define PCOS_COPYRIGHT \
        "(c) 2007 PDFlib GmbH  www.pdflib.com  sales@pdflib.com\n"

#define PCOS_MAJORVERSION	2
#define PCOS_MINORVERSION	0
#define PCOS_REVISION		0
#define PCOS_VERSIONSTRING	"2.0"

/* Opaque data type for the pCOS context. */
/* TODO: what is it good for? defined(pCOS) seems to be an error? */
#if !defined(pCOS) || defined(ACTIVEX)
typedef struct pCOS_s pCOS;
#endif

/*
 * Enabling "Enums are always int" is necessary because the
 * our libraries are compiled with this setting, and clients may use
 * a different setting.
 */
#if defined(__MWERKS__)
#pragma enumsalwaysint on
#endif

/*
 * ----------------------------------------------------------------------
 * pCOS-specific enums and defines
 * ----------------------------------------------------------------------
 */

/*
 * PDFlib GmbH products implement the following pCOS interface numbers:
 *
 * pCOS interface   Products
 * 1                TET 2.0.x
 * 2                pCOS 1.0.x
 */

#ifndef PCOS_INTERFACE
#define PCOS_INTERFACE	2

/* document access levels.
*/
typedef enum
{
    pcos_mode_minimum	 = 0, /* encrypted doc (opened w/o password)	      */
    pcos_mode_restricted = 1, /* encrypted doc (opened w/ user password)      */
    pcos_mode_full	 = 2  /* unencrypted doc or opened w/ master password */
} pcos_mode;


/* object types.
*/
typedef enum
{
    pcos_ot_null	= 0,
    pcos_ot_boolean	= 1,
    pcos_ot_number	= 2,
    pcos_ot_name	= 3,
    pcos_ot_string	= 4,
    pcos_ot_array	= 5,
    pcos_ot_dict	= 6,
    pcos_ot_stream	= 7,
    pcos_ot_fstream	= 8
} pcos_object_type;

#endif /* PCOS_INTERFACE */


/*
 * ----------------------------------------------------------------------
 * pCOS API functions
 * ----------------------------------------------------------------------
 */

/* Release a document handle and all internal resources related to that
** document.
*/
PDFLIB_API void PDFLIB_CALL
pCOS_close_document(
    pCOS *p,
    int doc);

/* Delete a pCOS context and release all related internal resources. */
PDFLIB_API void PDFLIB_CALL
pCOS_delete(pCOS *p);

/* Get the name of the API function which threw the most recent exception or
** failed.
*/
PDFLIB_API const char * PDFLIB_CALL
pCOS_get_apiname(
    pCOS *p);

/* Get the descriptive text of the last thrown exception, or the reason of a
** failed function call.
*/
PDFLIB_API const char * PDFLIB_CALL
pCOS_get_errmsg(
    pCOS *p);

/* Get the number of the last thrown exception, or the reason for a failed
** function call.
*/
PDFLIB_API int PDFLIB_CALL
pCOS_get_errnum(
    pCOS *p);

/* Fetch the opaque client pointer from with a pCOS context. Unsupported. */
PDFLIB_API void * PDFLIB_CALL
pCOS_get_opaque(pCOS *p);

/* Create a new pCOS context. */
PDFLIB_API pCOS * PDFLIB_CALL
pCOS_new(void);

/* Create a new pCOS context with a user-supplied error handler and
** opaque pointer. Unsupported.
*/
typedef void (*pcos_error_fp)(pCOS *p, int type, const char *msg);

PDFLIB_API pCOS * PDFLIB_CALL
pCOS_new2(pcos_error_fp errorhandler, void *opaque);

/* Open a PDF document. */
PDFLIB_API int PDFLIB_CALL
pCOS_open_document(
    pCOS *p,
    const char *filename,
    int len,
    const char *optlist);

/* Open a PDF document directly from memory. */
PDFLIB_API int PDFLIB_CALL
pCOS_open_document_mem(
    pCOS *p,
    const void *data,
    size_t size,
    const char *optlist);

/* Open a PDF document via a user-supplied function. */
PDFLIB_API int PDFLIB_CALL
pCOS_open_document_callback(
    pCOS *p,
    void *opaque,
    size_t filesize,
    size_t (*readproc)(void *opaque, void *buffer, size_t size),
    int (*seekproc)(void *opaque, long offset),
    const char *optlist);

/* Get the value of a pCOS path with type number or boolean. */
PDFLIB_API double PDFLIB_CALL
pCOS_get_number(
    pCOS *p,
    int doc,
    const char *path, ...);

/* Get the value of a pCOS path with type name, string, or boolean. */
PDFLIB_API const char * PDFLIB_CALL
pCOS_get_string(
    pCOS *p,
    int doc,
    const char *path, ...);

/* Get the contents of a pCOS path with type stream, fstream, or string. */
PDFLIB_API const unsigned char * PDFLIB_CALL
pCOS_get_stream(
    pCOS *p,
    int doc,
    int *length,
    const char *optlist,
    const char *path, ...);

/* Set one or more global options. */
PDFLIB_API void PDFLIB_CALL
pCOS_set_option(
    pCOS *p,
    const char *optlist);

/* Convert a string from UTF-8 format to UTF-16. */
PDFLIB_API const char * PDFLIB_CALL
pCOS_utf8_to_utf16(
   pCOS *p,
   const char *utf8string,
   const char *ordering,
   int *size);

/* Convert a string from UTF-16 format to UTF-8. */
PDFLIB_API const char * PDFLIB_CALL
pCOS_utf16_to_utf8(
    pCOS *p,
    const char *utf16string,
    int len,
    int *size);

/*
 * ----------------------------------------------------------------------
 * Exception handling with try/catch implementation
 * ----------------------------------------------------------------------
 */

/* Set up an exception handling frame; must always be paired with pCOS_CATCH().
*/
#define pCOS_TRY(p)		if (setjmp(pcos_jbuf(p)->jbuf) == 0)

/* Inform the exception machinery that a pCOS_TRY() will be left without
   entering the corresponding pCOS_CATCH( ) clause. */

#define pCOS_EXIT_TRY(p)	pcos_exit_try(p)

/* Catch an exception; must always be paired with pCOS_TRY(). */

#define pCOS_CATCH(p)		if (pcos_catch(p))

/* Re-throw an exception to another handler. */

#define pCOS_RETHROW(p)		pcos_rethrow(p)


/*
 * ----------------------------------------------------------------------
 * Private stuff, do not use explicitly but only via the above macros!
 * ----------------------------------------------------------------------
 */

#include <setjmp.h>

typedef struct
{
    jmp_buf	jbuf;
} pcos_jmpbuf;

PDFLIB_API pcos_jmpbuf * PDFLIB_CALL
pcos_jbuf(
    pCOS *p);

PDFLIB_API void PDFLIB_CALL
pcos_exit_try(
    pCOS *p);

PDFLIB_API int PDFLIB_CALL
pcos_catch(
    pCOS *p);

PDFLIB_API void PDFLIB_CALL
pcos_rethrow(
    pCOS *p);

PDFLIB_API void PDFLIB_CALL
pcos_throw(
    pCOS *p,
    const char *parm1,
    const char *parm2,
    const char *parm3);

#ifdef __cplusplus
}	/* extern "C" */
#endif

#if defined(__MWERKS__) && defined(PDFLIB_EXPORTS)
#pragma export off
#endif

#if defined(__MWERKS__)
#pragma enumsalwaysint reset
#endif

#endif /* PCOSLIB_H */
