/***************************************************************************
 *            qof-address.h
 *
 *  Thu Oct 21 12:44:36 2004
 *  Copyright  2004-2005  Neil Williams  <linux@codehelp.co.uk>
 ****************************************************************************/

/*
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Library General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
/** @addtogroup QOF
	@{ */
/** @addtogroup Addr Addresses and Contacts

	Addresses is probably the easiest QOF object to understand - all the entries
	are simple strings.

\todo Custom fields are not being read.

	@{ */
/** @file  qof-address.h
	@brief QOF address definitions for pilot-link
	@author Copyright (c) 2004 Neil Williams <linux@codehelp.co.uk>
*/

#ifndef _QOF_ADDRESS_H
#define _QOF_ADDRESS_H

#include <glib.h>
#include <qof.h>
#include "pi-address.h"
#include "qof-main.h"


#ifdef __cplusplus
extern "C"
{
#endif

#define PQ_MOD_ADDRESS "pilotqof-address"
	
/** \brief Example of QOF wrapping an existing object.

Note that both the Address_t struct and the QofInstance instance are
contained within the object, not referenced using just a pointer.
*/
typedef struct {
	QofInstance inst;
	Address_t wrap;
	char *category;
} qof_addr;

/** \brief create a new address

	Hack alert: This routine specifically sets a blank
	value in entry[19] - using g_new0() externally
	is not the same.
*/
qof_addr* address_create(QofBook*);

/** @name Packing and unpacking objects.

Each pilot-link object has a structure that reflects the
relevant database on the Palm in a binary form that can be easily
manipulated. This binary format needs to be converted (packed) before
it can be understood by the Palm and converted back (unpacked) before
to be usable in pilot-link. Each object therefore needs to be packed
(prior to writing to the Palm) and unpacked (after reading from
the Palm) using it's own specialised functions. QOF uses a generic
function pointer to call the correct function for the current
QOF object and this function then calls the correct pack or
unpack function for the underlying pilot-link object.
@{ */

/** \brief Pack an Address object for the Palm.

Convert the pilot-link object into a form suitable for
HotSync to the Palm.
*/
int address_pack(QofEntity *ent, gpointer user_data);

/** \brief Unpack and Address object from the Palm.

Convert the record read from the Palm HotSync into a
usable pilot-link object - itself contained within a
QOF object.
*/
int address_unpack(QofEntity *ent, gpointer user_data);

/** \brief free the memory associated with the pilot-link object.

Use specialised pilot-link functions to free the underlying
object. The QOF entity can then be freed without problems.
*/
int qof_address_free(QofEntity *ent, gpointer user_data);

int addr_appinfo_unpack(QofEntity *ent, gpointer user_data);

/** @} */

/** \brief Extended for pilot-link

Uses the standard QOF registration but adds a pilot_pack
registration that tells QOF how to deal with the pilot-link
objects contained within the QOF objects.
*/
gboolean AddressRegister (void);

#ifdef __cplusplus
}
#endif

#endif /* _QOF_ADDRESS_H */
/** @} */
/** @} */