gecko-dev/include/abcom.h

/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.0 (the "NPL"); you may not use this file except in
 * compliance with the NPL.  You may obtain a copy of the NPL at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the NPL is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
 * for the specific language governing rights and limitations under the
 * NPL.
 *
 * The Initial Developer of this code under the NPL is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
 * Reserved.
 */


#ifndef _AB_COM_H_
#define _AB_COM_H_

#include "xp_core.h"
#include "msgcom.h"
#include "abdefn.h"
#include "dirprefs.h"

#ifdef XP_CPLUSPLUS
class AB_Pane;
class AB_ContainerPane;
class AB_MailingListPane;
class AB_PersonPane;
class AB_NameCompletionCookie;
#else
typedef struct AB_Pane AB_Pane;
typedef struct AB_ContainerPane AB_ContainerPane;
typedef struct AB_MailingListPane AB_MailingListPane;
typedef struct AB_PersonPane AB_PersonPane;
typedef struct AB_NameCompletionCookie AB_NameCompletionCookie;
#endif

XP_BEGIN_PROTOS

#define AB_API extern "C"

/* #define FE_IMPLEMENTS_VISIBLE_NC */  /* as each platform uses the new API, we should set this flag */
/* #define MOZ_NEWADDR */ /* FE address book developers should uncomment this flag. Leave it commented for the tree */

/* XXX - It dun't work without it */
#define MOZ_NEWADDR 1

const ABID AB_ABIDUNKNOWN = 0;   /* Find a better home for this somewhere! */

/* new errors added by mscott for the 2 pane AB UI. I will eventually name this enumerated type AB_Error */
enum
{
	AB_SUCCESS = 0,
	AB_FAILURE,
	AB_INVALID_PANE,
	AB_INVALID_CONTAINER,
	AB_INVALID_ATTRIBUTE,
	AB_OUT_OF_MEMORY,
	AB_ENTRY_BEING_FETCHED,  /* introduced by virtual list view. all of the get entry attribute APIs can return this error code
								whenever we have to go get the desired result. In other words, it means the get is now asynch! */
	AB_INVALID_COMMAND,       /* returned by AB_Command and AB_GetCommandStatus when the pane you passed in does not accept the cmd you
							    wanted. */ 
	ABError_NullPointer,	  /* I'm trying to switch over to this new error model.....*/	
	ABError_InvalidAttribute,  /* I'm trying to switch over to this new error model.....*/
	ABError_UnknownFileFormat  /* returned when you try to import a file type the address book does not recognize */

};

/* these are the types of possible containers */
typedef enum
{
	AB_LDAPContainer,
	AB_MListContainer,       /* a mailing list */
	AB_PABContainer,          /* a personal AB */
	AB_UnknownContainer		 /* when we don't know what container type it is! */
} AB_ContainerType;

/* AB_ContainerAttributes define the types of information FEs can ask the BE about
   a AB_ContainerInfo in the ABContainerPane. */

typedef enum
{
	attribContainerType,	/* mailing list? LDAP directory? PAB? */
	attribName,				/* the name for the container */
	attribNumChildren,		/* how many child containers does this container have? */
	attribDepth,			/* container depth in the overall hierarchy. 0 == root ctr, 1 == one level below a root container, etc. */
	attribContainerInfo		/* FEs might want to get the container Info * for a line in the container pane */
} AB_ContainerAttribute;

typedef struct AB_ContainerAttribValue
{
	AB_ContainerAttribute attrib;	/* used to determine value of the union */
	union{
		char * string;			   
		int32 number;				/* used by numchildren & depth */
		AB_ContainerType containerType;
		AB_ContainerInfo * container;
	} u;
} AB_ContainerAttribValue;

typedef enum 
{
	AB_Drag_Not_Allowed	= 0x00000000,
	AB_Require_Copy		= 0x00000001,
	AB_Require_Move		= 0x00000002,
	AB_Default_Drag		= -1  /* 0xFFFFFFFF */
} AB_DragEffect; 

typedef enum 
{ 
		  AB_attribUnknown = 0,					/* unrecognized attribute */
          AB_attribEntryType,					/* mailing list or person entry */ 
		  AB_attribEntryID,
          AB_attribFullName, 
		  AB_attribFullAddress,					/* RFC822 address for an entry.....i.e. "John Smith <smith@netscape.com>" */
		  AB_attribVCard,						/* get the Vcard for an attribute */
          AB_attribNickName, 
          AB_attribGivenName,					
          AB_attribMiddleName, 
          AB_attribFamilyName, 
          AB_attribCompanyName, 
          AB_attribLocality, 
          AB_attribRegion, 
          AB_attribEmailAddress, 
          AB_attribInfo, 
          AB_attribHTMLMail, 
          AB_attribExpandedName, 
          AB_attribTitle, 
          AB_attribPOAddress, 
          AB_attribStreetAddress, 
          AB_attribZipCode, 
          AB_attribCountry, 
          AB_attribWorkPhone, 
          AB_attribFaxPhone, 
          AB_attribHomePhone, 
          AB_attribDistName,       
          AB_attribSecurity, 
          AB_attribCoolAddress, 
          AB_attribUseServer,
		  AB_attribPager,
		  AB_attribCellularPhone,
		  AB_attribDisplayName,
		  AB_attribWinCSID,			/* character set id */
		  AB_attribOther			/* any attrib with this value or higher is always a string type (our dyanmic attributes) */
} AB_AttribID;

typedef enum{
	AB_MailingList = 0,
	AB_Person,
	AB_NakedAddress
} AB_EntryType;

typedef struct AB_AttributeValue
{
	AB_AttribID attrib; /* we need this to know how to read the union */
	union{
		char * string;
		XP_Bool boolValue;
		AB_EntryType entryType;  /* mailing list or person entry */
		int16 shortValue;			 /* use for server type or WinCSID field */
	} u;
} AB_AttributeValue;

typedef struct AB_EntryAttributeItem{                                                                                                                           
        AB_AttribID id;                                                                                                                                         
        char * description;  /* resource string specifying a user-readable descr  */
        XP_Bool sortable;    /* is this attribute sortable? (may help FEs displa  */                                                                            
} AB_EntryAttributeItem;  

/* New Column ID structure used to abstract the columns in the AB_Pane used by the FEs from the attributes those columns actually
	represent. */
typedef enum{
	AB_ColumnID0 = 0,
	AB_ColumnID1,
	AB_ColumnID2,
	AB_ColumnID3,
	AB_ColumnID4,
	AB_ColumnID5,
	AB_ColumnID6,
	AB_NumberOfColumns   /* make sure this is always the last one!! */
} AB_ColumnID;

typedef struct AB_ColumnInfo{
	AB_AttribID attribID;   /* the attrib ID this column is displaying */
	char * displayString;   /* column display string */
	XP_Bool sortable;		/* is this column attribute sortable? i.e. phone number is not! */
} AB_ColumnInfo;


/*********************************************************************************************
	A poor man's msgCopyInfo struct. We use this to encapsulate any data we may need when
	running copy / move urls in the address book. The creator of the URL acquires each ctr
	and the url handler releases the containers when the url is done or interrupted
**********************************************************************************************/
typedef enum{
	AB_CopyInfoCopy = 0 ,
	AB_CopyInfoMove,
	AB_CopyInfoDelete
} AB_AddressCopyInfoState;

typedef struct _AB_AddressBookCopyInfo
{
	AB_ContainerInfo * destContainer;
	AB_ContainerInfo * srcContainer;
	ABID * idArray;
	int32 numItems;
	AB_AddressCopyInfoState state; /* used to determine what type of action to perform on the entries */
} AB_AddressBookCopyInfo;

int AB_FreeAddressBookCopyInfo(AB_AddressBookCopyInfo * abCopyInfo);  /* use this to free copy info structs */

/**********************************************************************************************
FE Call back functions. We'll show the types here...NOTE: FEs must now register their call back
functions through these APIs so the back end knows which return to use. 
 *********************************************************************************************/

 /* FEs must register this function with the appropriate pane, it is called by the back end in 
response to the following commands: AB_PropertiesCmd, AB_AddUserCmd, AB_AddMailingListCmd */

typedef int AB_ShowPropertySheetForEntryFunc (MSG_Pane * pane, MWContext * context);

int AB_SetShowPropertySheetForEntryFunc(
		MSG_Pane * abPane,
		AB_ShowPropertySheetForEntryFunc * func);


/* BE sets the type for the DIR_Server and hands it to the FEs to be displayed & filled out in a 
pane. It is called by the back end in response to the following commands: AB_PropertiesCmd, 
AB_NewLDAPDirectory, AB_NewAddressBook. */

typedef int AB_ShowPropertySheetForDirFunc(
		DIR_Server * server, 
		MWContext * context, 
		MSG_Pane * srcPane, /* BE will pass in the pane that was used to generate this call (usually the container pane) */
		XP_Bool newDirectory /* is it a new directory? */);

int AB_SetShowPropertySheetForDirFunc(
		MSG_Pane * abcPane,						/* container pane */
		AB_ShowPropertySheetForDirFunc * func);

/***************************************************************************************
 None pane-specific APIs. These function work on many panes 
 ***************************************************************************************/

int AB_ClosePane(MSG_Pane * pane);

/***************************************************************************************
	Virtual List View APIs. 
****************************************************************************************/

int AB_SetFEPageSizeForPane(
	MSG_Pane * abPane, 
	uint32 pageSize);  /* number of entries in the FE pane's view. That is, total # entries
					      the FE is concerned with at a time */

/***************************************************************************************
	Selection APIs. 
****************************************************************************************/
XP_Bool AB_UseExtendedSelection(
	MSG_Pane * pane);
int AB_AddSelection(
	MSG_Pane * pane,
	MSG_ViewIndex index); /* index of entry to add selection for */
XP_Bool AB_IsSelected(
		MSG_Pane * pane,
		MSG_ViewIndex index); /* index of entry to check for selection */
int AB_RemoveSelection(
	MSG_Pane * pane,
	MSG_ViewIndex index); /* index of entry to remove selection for */
void AB_RemoveAllSelections(
		MSG_Pane * pane);

/***************************************************************************************
    Replication APIs and Types.
****************************************************************************************/

AB_ContainerInfo *AB_BeginReplication(MWContext *context, DIR_Server *server);
int AB_EndReplication(AB_ContainerInfo *container);
int AB_AddReplicaEntry(AB_ContainerInfo *container, char **valueList);
int AB_DeleteReplicaEntry(AB_ContainerInfo *container, char *targetDn);
int AB_RemoveReplicaEntries(AB_ContainerInfo *container);
int AB_GetNumReplicaAttributes(AB_ContainerInfo *container);
char **AB_GetReplicaAttributeNames(AB_ContainerInfo *container);
XP_Bool AB_ReplicaAttributeMatchesId(AB_ContainerInfo *container, int attribIndex, DIR_AttributeId id);

/***************************************************************************************
	Type down and name completion APIs. Both actions are asynchronous. Type down generates
	a MSG_PaneNotifyTypeDownCompleted pane notification and name completion calls a FE
	regsitered call back. 
****************************************************************************************/
int AB_TypedownSearch(
		MSG_Pane * abPane, /* AB_Pane we are doing the type down against */
		const char * typedownValue, /* NULL terminated character string for type down value. Caller frees */
		MSG_ViewIndex startIndex);  /* if this is a refined typedown search, insert the start index. Else MSG_VIEWINDEXNONE */


typedef int AB_NameCompletionExitFunction(
		AB_NameCompletionCookie * cookie, /* object which encapsulates name completion result */
		int numResults,  /* number results we had. Result string is NULL if this is 0 or > 1 */
		void * FEcookie);  /* whatever you passed into the type down call, we pass back to you here */

#ifdef FE_IMPLEMENTS_VISIBLE_NC
int AB_NameCompletionSearch(
		MSG_Pane * NCResolutionPane, /* the picker pane to fill the results with */
		const char * completionValue, /* partial string to perform auto-complete on */
		AB_NameCompletionExitFunction * exitFunction, /* FE exit function BE calls when asynch op is done */
		XP_Bool userSeesPane, /* back end has different search behavior if the pane is currently visible to the user */
		void * FEcookie);  /* FE can pass in the address of the object asking for the name completion. Will return in exit func */
#else
int AB_NameCompletionSearch(
		MSG_Pane * NCResolutionPane, /* the picker pane to fill the results with */
		const char * completionValue, /* partial string to perform auto-complete on */
		AB_NameCompletionExitFunction * exitFunction, /* FE exit function BE calls when asynch op is done */
		void * FEcookie);  /* FE can pass in the address of the object asking for the name completion. Will return in exit func */
#endif

/****************************************************************************************
	Name completion returns a name completion cookie. These APIs are used to extract
	the various string components from the name completion cookie
*****************************************************************************************/

/* NC Display string is the "blurr" string you see in the composition pane. It could include
   extra column attributes like company and department as determined by a pref */
char * AB_GetNameCompletionDisplayString(AB_NameCompletionCookie * cookie);

/* Header String is the string the composer should insert into the composition pane. It could
be the name of a mailing list: "testList" or a user: "John Doe <johndoe@netscape.com>" */
char * AB_GetHeaderString(AB_NameCompletionCookie * cookie);

/* getting the expanded header string returns the display string unless the entry was a mailing
 list in which case you get addresses for all the people in the mailing list. */
char * AB_GetExpandedHeaderString(AB_NameCompletionCookie * cookie);

AB_EntryType AB_GetEntryTypeForNCCookie(AB_NameCompletionCookie * cookie);

int AB_FreeNameCompletionCookie(AB_NameCompletionCookie * cookie);

/****************************************************************************************
	Name completion resolution pane specific APIs. 
*****************************************************************************************/
int AB_CreateABPickerPane( /* bad terminology on my part...you are really creating a name completion resolution picker pane */
		MSG_Pane ** NCResolutionPane, /* BE creates one and passes it back to FE here */
		MWContext * context,
		MSG_Master * master,
		uint32 pageSize);  /* what is your page size going to be */

AB_ContainerType AB_GetEntryContainerType(
		MSG_Pane * abPickerPane,
		MSG_ViewIndex index);   /* the name completion result index you want the type for... */

AB_NameCompletionCookie * AB_GetNameCompletionCookieForIndex(
		MSG_Pane * abPickerPane,
		MSG_ViewIndex index); /* NC result index you want the type for */

/* returns a cookie for the naked address including the default domain name...*/
AB_NameCompletionCookie * AB_GetNameCompletionCookieForNakedAddress(const char * nakedAddress);

/****************************************************************************************
 Address Book Pane General APIs - creating, initializing, closing, changing containers,
	searching, etc.
*****************************************************************************************/

int AB_CreateABPane(
		MSG_Pane ** abPane,
		MWContext * context,
		MSG_Master * master);

int AB_InitializeABPane(
		MSG_Pane * abPane,
		AB_ContainerInfo * abContainer);


/* to change the container the abPane is currently displaying */
int AB_ChangeABContainer(
		MSG_Pane * abPane,
		AB_ContainerInfo * container);   /* the new containerInfo to display */

int AB_GetEntryIndex(
		MSG_Pane * abPane,
		ABID id,  /* entry id in the database */
		MSG_ViewIndex * index); /* FE allocated, BE fills with index */

int AB_GetABIDForIndex(
		MSG_Pane * abPane,
		MSG_ViewIndex index,
		ABID * id);  /* FE allocated. BE fills with the id you want */

int AB_SearchDirectoryAB2(
		MSG_Pane * abPane,
		char * searchString);

int AB_LDAPSearchResultsAB2(
		MSG_Pane * abPane,
		MSG_ViewIndex index,
		int32 num);

int AB_FinishSearchAB2(MSG_Pane * abPane);


int AB_CommandAB2(
		MSG_Pane * srcPane,  
		AB_CommandType command,
		MSG_ViewIndex * indices,
		int32 numIndices);

int AB_CommandStatusAB2(
		MSG_Pane * srcPane, 
		AB_CommandType command,
		MSG_ViewIndex * indices,
		int32 numIndices,
		XP_Bool * selectable_p,
		MSG_COMMAND_CHECK_STATE * selected_p,
		const char ** displayString,
		XP_Bool * plural_p);

/****************************************************************************************
 AB_ContainerInfo General APIs - adding users and a sender. Doesn't require a pane.
*****************************************************************************************/
int AB_AddUserAB2(
		AB_ContainerInfo * abContainer, /* the container to add the person to */
		AB_AttributeValue * values, /* FE defined array of attribute values for the new user. FE must free this array */
		uint16 numItems,
		ABID * entryID);			   /* BE returns the ABID for this new user */

int AB_AddUserWithUIAB2(
		MSG_Pane* pane, /* we need the src pane because it has the call back function for the person property sheet */
		AB_ContainerInfo * abContainer,
		AB_AttributeValue * values,
		uint16 numItems,
		XP_Bool lastOneToAdd);

int AB_AddSenderAB2(
		MSG_Pane * pane, /* need the pane to get the property sheet function and context */
		AB_ContainerInfo * abContainer,
		const char * author,
		const char * url);

/* the following is called by the msgdbview when it wants to add a name and a address to the specified container */
int AB_AddNameAndAddress(
		MSG_Pane * pane,
		AB_ContainerInfo * abContainer,
		const char *name, 
		const char *address, 
		XP_Bool lastOneToAdd);

/****************************************************************************************
Drag and Drop Related APIs - vcards, ab lines, containers, etc. 
*****************************************************************************************/

int AB_DragEntriesIntoContainer(
		MSG_Pane * srcPane,				/* could be an ABPane or ABCPane */
		const MSG_ViewIndex * srcIndices,  /* indices of items to be dragged */
		int32 numIndices,
		AB_ContainerInfo * destContainer,
		AB_DragEffect request);         /* copy or move? */

/* FE's should call this function to determine if the drag & drop they want to perform is
   valid or not. I would recommend calling it before the FE actually performs the drag & drop call */
AB_DragEffect AB_DragEntriesIntoContainerStatus(
		MSG_Pane * abPane,
		const MSG_ViewIndex * indices,
		int32 numIndices,
		AB_ContainerInfo * destContainer,
		AB_DragEffect request);        /* do you want to do a move? a copy? default drag? */

/***************************************************************************************

  Asynchronous copy APIs. These APIs are used by mkabook.cpp for asycnh copy/move/delete
  entry operations between containers. 

***************************************************************************************/

/* this API is called only by the back end...it is used to do all the dirty work for
   assembling a addbook-copy url and adding it to a queue for running */
int AB_CreateAndRunCopyInfoUrl( 
		MSG_Pane * pane, 
		AB_ContainerInfo * srcContainer, 
		ABID * idArray, 
		int32 numItems, 
		AB_ContainerInfo * destContainer, 
		AB_AddressCopyInfoState action);

int AB_BeginEntryCopy(
		AB_ContainerInfo * srcContainer, 
		MWContext * context, 
		AB_AddressBookCopyInfo * copyInfo,
		void ** copyCookie, /* filled by container, position in IDArray to be copied next */
		XP_Bool * copyFinished); /* container sets to TRUE if copy is finished */

int AB_MoreEntryCopy(
		AB_ContainerInfo * srcContainer,
		MWContext * context,
		AB_AddressBookCopyInfo * copyInfo,
		void ** copyCookie,
		XP_Bool * copyFinished);

int AB_FinishEntryCopy(
		AB_ContainerInfo * srcContainer,
		MWContext * context,
		AB_AddressBookCopyInfo * copyInfo,
		void ** copyCookie);

int AB_InterruptEntryCopy(
		AB_ContainerInfo * srcContainer,
		MWContext * context,
		AB_AddressBookCopyInfo * copyInfo,
		void ** copyCookie);

/****************************************************************************************
Importing and Exporting - ABs from files, vcards...
*****************************************************************************************/

typedef enum
{
	AB_Filename = 0,      /* char * in import and export APIs contain an FE allocated/freed filename */
	AB_PromptForFileName, /* prompt for file name on import or export */
	AB_Vcard,        
	AB_CommaList,    /* comma separated list of email addresses */
	AB_RawData       /* we don't know what it is, will try to extract email addresses */
} AB_ImportExportType;  

/* Note, besides the usual suspects for error return values, AB_ImportData can also return ABError_UnknownFileFormat
   when the address book does not recognize the import file type. In certain cases, the caller may try to import
   the unrecognized file format by calling a third party import utiltity. */
#ifdef FE_IMPLEMENTS_NEW_IMPORT
int AB_ImportData(
		MSG_Pane * pane, /* we need a pane in order to get the url queue */
		AB_ContainerInfo * destContainer,
		const char * buffer, /* could be a full path or NULL (if type = prompt for filename) or a block of data to be imported */
		int32 bufSize, /* how big is the buffer? */
		AB_ImportExportType dataType); /* valid types: All */
#else
int AB_ImportData(
	AB_ContainerInfo * destContainer,
	const char * buffer, /* could be a full path or NULL (if type = prompt for filename) or a block of data to be imported */
	int32 bufSize, /* how big is the buffer? */
	AB_ImportExportType dataType); /* valid types: All */

#endif

/* returns TRUE if the container accepts imports of the data type and FALSE otherwise */
XP_Bool AB_ImportDataStatus(
		AB_ContainerInfo * destContainer,
		AB_ImportExportType dataType);

/* exporting always occurs to a file unless the data type is vcard. Only valid export data types are: vcard, 
   filename, prompt for filename */

int AB_ExportData(
		AB_ContainerInfo * srcContainer,
		char ** buffer, /* filename or NULL. Or if type = Vcard, the BE allocated vcard. FE responosible for freeing it?? */
		int32 * bufSize, /* ignored unless VCard is data type in which case FE allocates, BE fills */
		AB_ImportExportType dataType); /* valid types: filename, prompt for filename, vcard */

/*** Import and Export APIs used in libnet to perform these operations asynchronously...***/
int AB_ImportBegin(
		AB_ContainerInfo * container, 
		MWContext * context,
		const char * fileName, 
		void ** importCookie, /* used by container to keep track of the import state */
		XP_Bool * importFinished); /* set to TRUE by container if we finished the import */

int AB_ImportMore(
		AB_ContainerInfo * container, 
		void ** importCookie, /* used by container to keep track of the import state */
		XP_Bool * importFinished);

int AB_ImportInterrupt(
		AB_ContainerInfo * container,
		void ** importCookie);

int AB_ImportFinish(
		AB_ContainerInfo * container,
		void ** importCookie);

int AB_ImportProgress(
		AB_ContainerInfo * container,
		void * importCookie,
		uint32 * position,   /* the line we are on in the file */
		uint32 * fileLength, /* total # of lines in the file */
		uint32 * passCount); /* the pass we are on (out of 2) */

int AB_ExportBegin(
		AB_ContainerInfo * container,
		MWContext * context,
		const char * fileName,
		void ** exportCookie, /* used by container info to keep track of the export state */
		XP_Bool * exportFinished); /* set to TRUE by container if the export has finished */

int AB_ExportMore(
		AB_ContainerInfo * container,
		void ** exportCookie,
		XP_Bool * exportFinished);

int AB_ExportInterrupt(
		AB_ContainerInfo * container,
		void ** exportCookie);

int AB_ExportFinish(
		AB_ContainerInfo * container,
		void ** exportCookie);

int AB_ExportProgress(
		AB_ContainerInfo * container,
		void * exportCookie,
		uint32 * numberExported,  /* # of entries in the container we have exported so far */
		uint32 * totalEntries);   /* total # of entries in the address book */

/* used only in the back end to generate add ldap to abook urls and adds them to the url queue...
	For each entry, we fire off an ldap url to fetch its attributes..*/
int AB_ImportLDAPEntriesIntoContainer(
		MSG_Pane * pane,			/* source pane */
		const MSG_ViewIndex * indices,  /* selected indices in the src pane to add */
		int32 numIndices,    
		AB_ContainerInfo * destContainer);	/* destination container to add the selections too */

/****************************************************************************************

	ABContainer Pane --> Creation, Loading, getting line data for each container. 

*****************************************************************************************/
int AB_CreateContainerPane(
		MSG_Pane ** abContainerPane, /* BE will pass back ptr to pane through this */
		MWContext * context,
		MSG_Master * master);

int  AB_InitializeContainerPane(MSG_Pane * abContainerPane);

/* this will return MSG_VIEWINDEXNONE if the container info is not in the pane */
MSG_ViewIndex AB_GetIndexForContainer(
		MSG_Pane * abContainerPane,
		AB_ContainerInfo * container);   /* container you want the index for */ 

/* this will return NULL if the index is invalid */
AB_ContainerInfo * AB_GetContainerForIndex(
		MSG_Pane * abContainerPane, 
		const MSG_ViewIndex index);

/* the following set of APIs support getting/setting container pane line data out such as the container's
   name, type, etc. We are going to try a particular discipline for memory management of AB_ContainerAttribValues.
   For APIs which get an attribute value, the BE will actually allocate the struct. To free the space, the FE should
   call AB_FreeContainerAttribValue. For any API which sets an attribute value, the FE is responsible for allocating and
   de-allocating the data. */

int AB_GetContainerAttributeForPane(
		MSG_Pane * abContainerPane,
		MSG_ViewIndex index,			  /* index of container you want information for */
		AB_ContainerAttribute attrib,     /* attribute FE wants to know */
		AB_ContainerAttribValue ** value);  /* BE allocates struct. FE should call AB_FreeContainerAttribValue to free space when done */

int AB_SetContainerAttributeForPane(
		MSG_Pane * abContainerPane,
		MSG_ViewIndex index,
		AB_ContainerAttribValue * value); /* FE handles all memory allocation! */

int AB_GetContainerAttribute(
		AB_ContainerInfo * ctr,
		AB_ContainerAttribute attrib,
		AB_ContainerAttribValue ** value); /* BE allocates struct. FE should call AB_FreeContainerAttribValue to free space when donee */

int AB_SetContainerAttribute(
		AB_ContainerInfo * ctr,
		AB_ContainerAttribValue * value); /* FE handles all memory allocateion / deallocation! */

int AB_GetContainerAttributes(
		AB_ContainerInfo * ctr,
		AB_ContainerAttribute * attribsArray,
		AB_ContainerAttribValue ** valuesArray,
		uint16 * numItems);

int AB_SetContainerAttributes(
		AB_ContainerInfo * ctr,
		AB_ContainerAttribValue * valuesArray,
		uint16 numItems);

/* getting and setting multiple container attributes on a per container pane basis */
int AB_GetContainerAttributesForPane(
		MSG_Pane * abContainerPane,
		MSG_ViewIndex index,
		AB_ContainerAttribute * attribsArray,
		AB_ContainerAttribValue ** valuesArray,
		uint16 * numItems);

int AB_SetContainerAttributesForPane(
		MSG_Pane * abContainerPane,
		MSG_ViewIndex index,
		AB_ContainerAttribValue * valuesArray,
		uint16 numItems);

int AB_FreeContainerAttribValue(AB_ContainerAttribValue * value);  /* BE will free the attribute value */

int AB_FreeContainerAttribValues(AB_ContainerAttribValue * valuesArray, uint16 numItems);

XP_Bool AB_IsStringContainerAttribValue(AB_ContainerAttribValue * value); /* use this to determine if your attrib is a string attrib */


/* Use the following two functions to build the combo box in the Address Window of all the root level containers.
	You first ask for the number of root level (PABs and LDAP directories). Use this number to allocate an array of
	AB_ContainerInfo ptrs. Give this array to the back end and we will fill it. FE can destroy array when done with it.
	FE shoud NOT be deleting the individual AB_ContainerInfo ptrs. */

int AB_GetNumRootContainers(
		MSG_Pane * abContainerPane,
		int32 * numRootContainers);

int AB_GetOrderedRootContainers(
		MSG_Pane * abContainerPane,
		AB_ContainerInfo ** ctrArray, /* FE Allocated & Freed */
		int32 * numCtrs); /* in - # of elements in ctrArray. out - BE fills with # root containers stored in ctrArray */

/* sometimes you want to get a handle on the DIR_Sever for a particular container. Both return NULL if for some
   reason there wasn't a DIR_Server. If the container is a mailing list, returns DIR_Server of the PAB the list is in. 
   NOTE: If you modify any of the DIR_Server properties, you should call AB_UpdateDIRServerForContainer to make sure that the container
   (and hence any pane views on the container) are updated */ 

DIR_Server * AB_GetDirServerForContainer(AB_ContainerInfo * container);

/* Please don't call this function. It is going away!!! Use AB_UpdateDirServerForContainerPane instead!! */
int AB_UpdateDIRServerForContainer(AB_ContainerInfo * container);

/* will create a new container in the container pane if the directory does not already exist. Otherwise updates the
   directory's container in the pane */
int AB_UpdateDIRServerForContainerPane(
		MSG_Pane * abContainerPane,
		DIR_Server * directory);

/********************************************************************************************************************
 Our New Column Header APIs. We'll be phasing out AB_GetNumEntryAttributesForContainer and AB_GetEntryAttributesForContainer
 ********************************************************************************************************************/

AB_ColumnInfo * AB_GetColumnInfo(
		AB_ContainerInfo * container,
		AB_ColumnID columnID);

int AB_GetNumColumnsForContainer(AB_ContainerInfo * container);

int AB_GetColumnAttribIDs(
		AB_ContainerInfo * container, 
		AB_AttribID * attribIDs, /* FE allocated array of attribs. BE fills with values */
		int * numAttribs);       /* FE passes in # elements allocated in array. BE returns # elements filled */

/* we also have pane versions which are used by the picker pane */
AB_ColumnInfo * AB_GetColumnInfoForPane(
		MSG_Pane * abPickerPane,
		AB_ColumnID columnID);   /* ID for the column you want the info for */

int AB_GetNumColumnsForPane(MSG_Pane * abPickerPane);

int AB_GetColumnAttribIDsForPane(
		MSG_Pane * abPickerPane, 
		AB_AttribID * attribIDs, /* FE allocated array of attribs. BE fills with values */
		int * numAttribs);       /* FE passes in # elements allocated in array. BE returns # elements filled */

int AB_FreeColumnInfo(AB_ColumnInfo * columnInfo);

/****************************************************************************************
AB Pane List Data -> how to get ab pane line attributes such as name, address, phone, etc.
*****************************************************************************************/

/* to actually get an entry attribute */ 

int AB_GetEntryAttributeForPane(
		MSG_Pane * abPane,
		MSG_ViewIndex index,
		AB_AttribID attrib,            /* what attribute do you want? */
		AB_AttributeValue ** valueArray);     /* BE handles memory allocation. FE must call AB_FreeEntryAttributeValue when done */

int AB_GetEntryAttribute( 
		AB_ContainerInfo * container, 
		ABID entryid,               /* an identifier or key used to name the object in the container */ 
		AB_AttribID attrib,        /* attribute type the FE wants to know */ 
		AB_AttributeValue ** valueArray);   /* BE handles memory allocation. FE must call AB_FreeEntryAttributeValue when done */

int AB_SetEntryAttribute( 
		AB_ContainerInfo * container,
		ABID entryid,               /* an identifier or key used to name the object in the container */ 
		AB_AttributeValue * value);   /* FE handles all memory allocation */

int AB_SetEntryAttributeForPane( 
		MSG_Pane * abPane,
		MSG_ViewIndex index,
		AB_AttributeValue * value);   /* FE handles all memory allocation */

/* we also allow you to set entry attributes in batch by passing in an array of attribute values */
int AB_SetEntryAttributes(
		AB_ContainerInfo * container,
		ABID entryID,
		AB_AttributeValue * valuesArray, /* FE allocated array of attribute values to set */
		uint16 numItems);  /* FE passes in # items in array */

int AB_SetEntryAttributesForPane(
		MSG_Pane * abPane,
		MSG_ViewIndex index,
		AB_AttributeValue * valuesArray,
		uint16 numItems);

int AB_GetEntryAttributes(
		AB_ContainerInfo * container,
		ABID entryID,
		AB_AttribID * attribs, /* FE allocated array of attribs that you want */
		AB_AttributeValue ** values, /* BE allocates & fills an array of values for the input array of attribs */
		uint16 * numItems);  /* IN: size of attribs array. OUT: # of values in value array */

int AB_GetEntryAttributesForPane(
		MSG_Pane * abPane,
		MSG_ViewIndex index,
		AB_AttribID * attribs, /* FE allocated array of attribs that you want */
		AB_AttributeValue ** values,
		uint16 * numItems);

/* Memory allocation APIs for setting/getting entry attribute values */
int AB_FreeEntryAttributeValue(AB_AttributeValue  * value /* pointer to a value */); 
int AB_FreeEntryAttributeValues(AB_AttributeValue * values /* array of values */, uint16 numItems);

int AB_CopyEntryAttributeValue(
		AB_AttributeValue * srcValue, /* already allocated attribute value you want to copy from */
		AB_AttributeValue * destValue); /* already allocated attribute value you want to copy into */

/* Assigns a default value for the given attribute and stores it in the attribute value passed in */
int AB_CopyDefaultAttributeValue(
		AB_AttribID attrib, 
		AB_AttributeValue * value /* already allocated */);

/* I think this API is used only by the back end...*/
int AB_CreateAttributeValuesForNakedAddress(
		char * nakedAddress, 
		AB_AttributeValue ** valueArray, /* caller must free returned array */
		uint16 * numItems);

int AB_GetAttributesForNakedAddress(
		char * nakedAddress,
		AB_AttribID * attribs, /* caller allocated array of attribs that you want */
		AB_AttributeValue ** values, /* BE allocates & fills an array of values for the input array of attribs.Caller ust later free */
		uint16 * numItems);			 /* IN: size of attribs array. OUT: # of values in value array */

XP_Bool AB_IsStringEntryAttributeValue(AB_AttributeValue * value);

/****************************************************************************************
Sorting 
*****************************************************************************************/

/* sorting by first name is a global setting. It is set per abPane and does not change
    when you load a new container into the abPane */

XP_Bool AB_GetSortByFirstNameAB2(MSG_Pane * abPane);  /* is the pane sorting by first name? */

void AB_SortByFirstNameAB2(
		MSG_Pane * abPane,
		XP_Bool sortByFirstName);   /* true for sort by first, false for last first */

/* Insert our sort by column stuff here */
int AB_SortByAttribute(
		MSG_Pane * abPane,
		AB_AttribID id,				/* attribute we want to sort by */
		XP_Bool sortAscending);

int AB_GetPaneSortedByAB2(
		MSG_Pane * abPane,
		AB_AttribID * attribID);  /* BE fills with the attribute we are sorting by */


XP_Bool AB_GetPaneSortedAscendingAB2(MSG_Pane * abPane);

/*****************************************************************************************
 APIs for the Mailing List Pane. In addition to these, the mailing list pane responds to 
 previous AB APIs such as AB_Close, MSG_GetNumLines(). 
 ****************************************************************************************/
int AB_InitializeMailingListPaneAB2(MSG_Pane * mailingListPane);

AB_ContainerInfo * AB_GetContainerForMailingList(MSG_Pane * mailingListPane); 

/* Use these two APIs to add entries to the mailing list that are the result of name completion. */
int AB_AddNakedEntryToMailingList(
		MSG_Pane * mailingListPane,
		const MSG_ViewIndex index, /* index in pane to add the element at. Use MSG_VIEWINDEXNONE to signify don't care */
		const char * nakedAddress, /* entry was not a name completion match, but a naked adddress */
		XP_Bool ReplaceExisting);  /* TRUE if replace current entry, FALSE for inserting */

int AB_AddNCEntryToMailingList(
		MSG_Pane * mailingListPane,
		const MSG_ViewIndex index, 
		AB_NameCompletionCookie * cookie, /* result from name completion code. FE must still free the cookie */
		XP_Bool ReplaceExisting);

/* this could return ABID = 0 for a new entry that is not in the database */
ABID AB_GetABIDForMailingListIndex(
		MSG_Pane * mailingListPane,
		const MSG_ViewIndex index);

MSG_ViewIndex AB_GetMailingListIndexForABID(
		MSG_Pane * mailingListPane,
		ABID entryID); /* this function could return MSG_VIEWINDEXNONE if entryID = 0 or not in list */

/* Use these two APIs to get Mailing List ENTRY attributes (i.e. people or other mailing list attributes in this mailing list) */
int AB_SetMailingListEntryAttributes(
		MSG_Pane * pane,
		const MSG_ViewIndex index,
		AB_AttributeValue * valuesArray, /* FE allocated array of attribute values you want to set */
		uint16 numItems);

int AB_GetMailingListEntryAttributes(
		MSG_Pane * mailingListPane, 
		const MSG_ViewIndex index,
		AB_AttribID * attribs, /* FE allocated & freed array of attribs you want */
		AB_AttributeValue ** values, /* BE allocates & fills values for the input array of attribs */
		uint16 * numItems); /* FE provides # attribs in array. BE fills with # values returned in values */

/* Use these two APIs to Set and Get the Mailing List properties. */
int AB_GetMailingListAttributes(
		MSG_Pane * mailingListPane,
		AB_AttribID * attribs,			/* FE allocated array of attribs */
		AB_AttributeValue ** values,  /* BE allocates & fills values. FE must call a free to the back end */
		uint16 * numItems);
		
int AB_SetMailingListAttributes(
		MSG_Pane * mailingListPane, 
		AB_AttributeValue * valuesArray, /* FE allocated array of attribute values you want to set */
		uint16 numItems);


/*******************************************************************************************
APIs for the person entry pane aka the person property sheets. The person entry pane is created 
by the back end and given to the front end in the call FE_ShowPropertySheetFor. In the current
incarnation, person atributes are set and retrieved through the person entry pane and NOT through
the AB_ContainerInfo the person is in. If you "cheat" and go through the container directly, you may
not be getting the correct information. When the person entry pane is committed, the changes are pushed
back into the container. During the commit process, if it is a new person then a new entry is made in the
database.
********************************************************************************************/
AB_ContainerInfo * AB_GetContainerForPerson(MSG_Pane * personPane);

ABID AB_GetABIDForPerson(MSG_Pane * personPane); /* could return 0 if new user */

/* get and set the person attributes here */
int AB_SetPersonEntryAttributes(
		MSG_Pane * personPane,
		AB_AttributeValue * valuesArray,
		uint16 numItems);

int AB_GetPersonEntryAttributes(
		MSG_Pane * personPane,
		AB_AttribID * attribs, /* FE allocted & freed array of attribs they want */
		AB_AttributeValue ** values, /* BE allocates & fills values */
		uint16 * numItems); /* in - FE provides # of attribs. out - BE fills with # values */

int AB_CommitChanges(MSG_Pane * pane); /* commits changes to a mailing list pane or a person entry pane! */


/* FEs should use this to obtain a property sheet pane representing the user's identity vcard...*/
int AB_GetIdentityPropertySheet(
		MWContext *context, 
		MSG_Master * master, 
		MSG_Pane ** pane);

/**********************************************************************************************
	Miscellaneous APIs which need to be public to folks outside of libaddr. Not necessarily
	used by the FES..

***********************************************************************************************/

int AB_SplitFullName (
		const char *fullName, 
		char **firstName, 
		char **lastName, 
		int16 csid);

/* use the default display name API for generating a display name in the person property sheet card for new users */
int AB_GenerateDefaultDisplayName(
		const char * firstName, 
		const char * lastName, 
		char ** defaultDisplayName /* calller must free with XP_FREE */);

XP_List * AB_AcquireAddressBookContainers(MWContext * context);

int AB_ReleaseContainersList(XP_List * containers);

int AB_AcquireContainer(AB_ContainerInfo * container);
int AB_ReleaseContainer(AB_ContainerInfo * container); 

/* should not be called by FEs....they should use AB_ImportData.....
   This function iterates over all of the vcard objects in the string and adds each one to the container 
*/
int AB_ImportVCards(
		AB_ContainerInfo * destContainer, 
		const char * vCardString);

/* the following are only used in libaddr...not by the FEs...*/
int AB_ConvertVCardToAttribValues( /* import.cpp */
		const char * vCard, 
		AB_AttributeValue ** values,  /* function allocates, caller must free */
		uint16 * numItems);

int AB_ConvertAttribValuesToVCard(   /* export.cpp */
		AB_AttributeValue * values, 
		uint16 numItems,
		char **VCard); /* function allocates...caller must free with XP_FREE */

int AB_ExportVCardToPrefs(const char * VCardString); /* import.cpp */

/* Used by libmsg compose pane to attach a vcard file to the message */
int AB_ExportVCardToTempFile (  /* export.cpp */
		const char * vCard, 
		char** filename);

/* used to load the current user's vcard from preferences. Caller must free */
int AB_LoadIdentityVCard(char ** IdentityVCard); /* import.cpp */ 

XP_END_PROTOS

#endif /* _AB_COM_H */