diff --git a/mozilla/cmd/winfe/abapi.h b/mozilla/cmd/winfe/abapi.h new file mode 100644 index 00000000000..60ff8941524 --- /dev/null +++ b/mozilla/cmd/winfe/abapi.h @@ -0,0 +1,297 @@ +/* -*- Mode: C++; tab-width: 4; 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. + */ +// +// This is a header file for the Address Book API support within +// Communicator. +// +// Written by: Rich Pizzarro (rhp@netscape.com) +// +#ifndef __ABAPI +#define __ABAPI + +#include "nabapi.h" // for all address book defines + +// These are very important for compatibility going forward... +#define NAB_VERSION_MAJOR 1 /* Major version number; changes with major code release number */ +#define NAB_VERSION_MINOR 0 /* Minor version number; changes with point release number. */ + +#ifdef WIN16 +typedef unsigned char UCHAR; +#endif + +#define MAX_NAME_LEN 256 +#define MAX_ADDRBOOK_NAME_LEN 512 +#define MAX_CON 4 // Maximum NABAPI sessions supported +#define MAX_POINTERS 32 +#define MAX_LDIF_SIZE 16000 // Max size for address book LDIF allocation stuff +#define MAX_LDIFSEARCH_SIZE 4096 // Max size for address book LDIF allocation stuff + +#ifndef NABAPIDLL + +#include "abcom.h" // For MSG_ & AB_ stuff... +#include "msgcom.h" + +// +// The Address Book class that will act as the internal mechanism for +// Communicator to control multiple Address Book sessions. +// +class CNABConnection +{ +protected: + LONG m_ID; + BOOL m_defaultConnection; + LONG m_sessionCount; + LONG m_nameIndex; + LONG m_nameTotalCount; + + // Methods +public: + MSG_Pane *m_ContainerPane; // Container Pane... + AB_ContainerInfo **m_ContainerArray; // The array of container info pointers... + LONG m_ContainerArrayCount; // The count of the number of + // m_ContainerArray entries + MSG_Pane *m_AddressBookPane; // Container info for a particular addr book + + CNABConnection ( LONG ); + ~CNABConnection ( ); + + // ID related methods + LONG GetID( ) { return m_ID; } ; + + // Dealing with the default session... + BOOL IsDefault( ) { return m_defaultConnection; } ; + void SetDefault( BOOL flag ) { m_defaultConnection = flag; } ; + + // For handling multiple sessions on a profile name... + LONG GetSessionCount( ) { return m_sessionCount; } ; + void IncrementSessionCount() { ++m_sessionCount; } ; + void DecrementSessionCount() { --m_sessionCount; } ; + + // For enumerating names... + void SetNameIndex( LONG mIndex ) { m_nameIndex = mIndex; } ; + void IncrementNameIndex( ) { ++m_nameIndex; } ; + LONG GetNameIndex( ) { return m_nameIndex; }; + + void SetNameTotalCount( LONG mTotal ) { m_nameTotalCount = mTotal; } ; + LONG GetNameTotalCount( ) { return m_nameTotalCount; }; + + // For AB Calls... + BOOL RefreshABContainerList ( void ); + AB_ContainerInfo *FindContainerInfo( LPSTR, LPSTR ); + + +}; + +#endif // NABAPIDLL + +// +// Defines needed for requests being made with the WM_COPYDATA call... +// +typedef enum { + NSCP_NABStartRequestID = 200, + NSCP_NAB_Open, + NSCP_NAB_Close, + NSCP_NAB_GetAddressBookList, + NSCP_NAB_GetDefaultAddressBook, + NSCP_NAB_CreatePersonalAddressBook, + NSCP_NAB_FreeMemory, + NSCP_NAB_SaveAddressBookToHTML, + NSCP_NAB_ImportLDIFFile, + NSCP_NAB_ExportLDIFFile, + NSCP_NAB_GetFirstAddressBookEntry, + NSCP_NAB_GetNextAddressBookEntry, + NSCP_NAB_FindAddressBookEntry, + NSCP_NAB_InsertAddressBookEntry, + NSCP_NAB_UpdateAddressBookEntry, + NSCP_NAB_DeleteAddressBookEntry, + NSCP_NABEndRequestID // Note: this is a marker for NAB IPC requests +} NSCP_NAB_IPC_REQUEST; + +// +// This is to keep track of the pointers allocated in the MAPI DLL +// and deal with them correctly. +// +#define NAB_FLAT_MEMORY 0 +#define NAB_ADDRBOOK_STRUCT 1 + +typedef struct { + LPVOID lpMem; + char memType; +} nabMemTrackerType; + +// +// This is the generic message that WM_COPYDATA will send to the +// Communicator product to allow it to attach to shared memory. +// NOTE: On Win16, this will simply reference a pointer. +// +typedef struct { + char smemName[64]; // Name of shared memory + DWORD smemSize; // Size of shared memory + LPVOID lpsmem; // Will be really used in Win16 only +} NABIPCType; + +// +// These are message specific structures that will be used for +// the various Address Book operations. +// +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + UINT_16 majorVerNumber; + UINT_16 minorVerNumber; +} NAB_OpenType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; +} NAB_CloseType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + UINT_32 abookCount; + char blobFileName[_MAX_PATH]; // file name N abooks on disk +} NAB_GetAddressBookListType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + BOOL defaultFound; + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookDesc[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk +} NAB_GetDefaultAddressBookType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookName[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk +} NAB_CreatePersonalAddressBookType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookName[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk + // Return stuff + char HTMLFileName[_MAX_PATH]; // saved HTML file name +} NAB_SaveAddressBookToHTMLType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + BOOL deleteImportFile; + char LDIFFileName[_MAX_PATH]; // LDIF file to import + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookName[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk +} NAB_ImportLDIFFileType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + char LDIFFileName[_MAX_PATH]; // LDIF file to export + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookName[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk +} NAB_ExportLDIFFileType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookName[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk + // Returned Values + NABUserID userID; + NABUpdateTime updateTime; + char userInfo[MAX_LDIF_SIZE]; +} NAB_GetFirstAddressBookEntryType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + // NABAddrBookDescType flattened + char reserved[16]; // future use + // Returned Values + NABUserID userID; + NABUpdateTime updateTime; + char userInfo[MAX_LDIF_SIZE]; +} NAB_GetNextAddressBookEntryType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookName[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk + // Input Values + char ldifSearchAttribute[MAX_LDIFSEARCH_SIZE]; + // Output values + NABUserID userID; + NABUpdateTime updateTime; + char userInfo[MAX_LDIF_SIZE]; +} NAB_FindAddressBookEntryType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookName[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk + // Insert Value + char userInfo[MAX_LDIF_SIZE]; + // Update Value + NABUserID userID; +} NAB_InsertAddressBookEntryType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookName[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk + // Update Value + NABUserID userID; + char userInfo[MAX_LDIF_SIZE]; +} NAB_UpdateAddressBookEntryType; + +typedef struct { + DWORD ipcWorked; // Necessary for IPC check with Communicator + NABConnectionID abConnection; + // NABAddrBookDescType flattened + char reserved[16]; // future use + char abookName[MAX_ADDRBOOK_NAME_LEN]; // description of address book + char abookFileName[_MAX_PATH]; // file name of abooks on disk + // Delete user Value + NABUserID userID; +} NAB_DeleteAddressBookEntryType; + +#endif // __ABAPI diff --git a/mozilla/cmd/winfe/nabapi.h b/mozilla/cmd/winfe/nabapi.h new file mode 100644 index 00000000000..1871a1f7715 --- /dev/null +++ b/mozilla/cmd/winfe/nabapi.h @@ -0,0 +1,491 @@ +/* -*- Mode: C++; tab-width: 4; 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 __NABAPI_H__ +#define __NABAPI_H__ + +/******************************************************** + * Structures, Type Definitions & Return Codes + ********************************************************/ + +#ifndef _UINT_16 +typedef unsigned short UINT_16; +#endif +#ifndef _UINT_32 +typedef unsigned long UINT_32; +#endif +#ifndef _INT_16 +typedef short INT_16; +#endif +#ifndef _INT_32 +typedef long INT_32; +#endif + +#ifndef FALSE +#define FALSE (0) +#endif +#ifndef TRUE +#define TRUE (1) +#endif +#ifndef NULL +#define NULL (0L) +#endif + +typedef unsigned char NABBool; +typedef long NABError; +typedef short NABReason; +typedef long NABAddrBookID; +typedef long NABUserID; +typedef long NABFieldMask; +typedef unsigned long NABUpdateTime; +typedef unsigned long NABConnectionID; + +typedef enum { + NAB_SUCCESS, /* The API call succeeded. */ + NAB_FAILURE, /* This is a generic API failure. */ + NAB_INVALID_CONNID, /* Invalid Connection ID for request */ + NAB_NOT_OPEN, /* This will be returned when a call is made to the API without NAB_Open() being called first. */ + NAB_NOT_FOUND, /* The requested information was not found. */ + NAB_PERMISSION_DENIED, /* User does not have write permission to perform the operation */ + NAB_DISK_FULL, /* Disk full condition encountered attempting to perform the operation */ + NAB_INVALID_NAME, /* The name specified for the operation is invalid */ + NAB_INVALID_ABOOK, /* The address book specified is invalid */ + NAB_FILE_NOT_FOUND, /* The disk file for the operation was not found */ + NAB_ALREADY_EXISTS, /* The user entry already exists in the address book being updated */ + NAB_MAXCON_EXCEEDED,/* The maximum number of API connections has been exceeded */ + NAB_MEMORY_FAILURE, /* Memory condition, such as malloc() failures */ + NAB_FILE_ERROR, /* Error on file creation */ + NAB_INVALID_ENTRY, /* Invalid entry for operation */ + NAB_MULTIPLE_USERS_FOUND, /* More than one person found with current search criteria */ + NAB_INVALID_SEARCH_ATTRIB /* Invalid search criteria */ +} NAB_ERROR_CODE_TYPES; + +typedef struct +{ + char *description; // Description of address book - MUST BE UNIQUE + char *fileName; // The file name of the address book +} NABAddrBookDescType; + +// Used to separate return values for the LDIF formatted lines +#define NAB_CRLF "\r\n" + +/******************************************************** + * Initialization Calls + ********************************************************/ +/* + * NAB_Open() will start the connection to the API. It will initialize any necessary + * internal variables and return the major and minor version as defined here. This + * will allow client applications to verify the version they are running against. + * + * Return Value: + * NAB_SUCCESS - The API was opened successfully and is ready to process other API calls. + * NAB_FAILURE - The API open operation failed. + * NAB_MAXCON_EXCEEDED - The maximum number of connections to the API has been exceeded. + * + * Parameters: + * id - the pointer to a connection ID that will be filled out by the open call. This needs + * to be used in other API calls. ZERO is invalid. + * majorVerNumber - this is a pointer to a UNIT_16 for the MAJOR version number of the API + * minorVerNumber - this is a pointer to a UNIT_16 for the MINOR version number of the API + */ +NABError NAB_Open(NABConnectionID *id, UINT_16 *majorVerNumber, UINT_16 *minorVerNumber); + +/* + * This closes the connection to the API. Any subsequent call to the NABAPI will fail with + * an NAB_NOT_OPEN return code. + * + * Return Value: + * NAB_SUCCESS - The API was opened successfully and is ready to process other API calls. + * NAB_FAILURE - The API open operation failed. + * Parameters: + * id - the connection ID returned by the NAB_Open() call + */ +NABError NAB_Close(NABConnectionID id); + +/******************************************************** + * Address Book Information Calls + ********************************************************/ + +/* + * This call will return a list of pointers to the list of available address + * books in NABAddrBookDescType format. The memory for this array will be allocated + * by the NABAPI and the caller is responsible for freeing the memory with a call + * to the NAB_FreeMemory() function call. NOTE: The call to NAB_FreeMemory() must be + * made for each entry in the returned array and not just a pointer to the array itself. + * The number of address books found will also be returned in the abookCount + * argument to the call. If the returned list is NULL or the abookCount value is + * less than or equal to ZERO, no address books were found. + * + * Return Value: + * NAB_SUCCESS - The operation succeeded and the next entry was found. + * NAB_FAILURE - General failure getting the next address book entry + * NAB_NOT_FOUND - No address books were found + * NAB_NOT_OPEN - This will be returned when a call is made to the API without NAB_Open() being called first. + * NAB_INVALID_CONNID - Invalid connection ID + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * abookCount - a pointer to a UINT_32 where the API will store the number of + * address books found and returned to the caller + * aBooks - A pointer to an array of NABAddrBookDescType structures. If no entries are + * available, a NULL list is returned to the caller. + */ +NABError NAB_GetAddressBookList(NABConnectionID id, UINT_32 *abookCount, NABAddrBookDescType *aBooks[]); + +/* + * This call will return the default address book for the client. If the + * returned value is NULL, no default address book was found. The memory + * for this return value will be allocated by the ABAPI and the caller is + * responsible for freeing the memory with a call to the NAB_FreeMemory() + * function call. + * + * Return Value: + * NAB_SUCCESS - The operation succeeded and the next entry was found. + * NAB_FAILURE - General failure getting the next address book entry + * NAB_NOT_FOUND - No address books were found + * NAB_NOT_OPEN - This will be returned when a call is made to the API without NAB_Open() being called first. + * NAB_INVALID_CONNID - Invalid connection ID + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * aBook - A pointer to an NABAddrBookDescType structure. If no default address + * book is found, NULL returned to the caller. + */ +NABError NAB_GetDefaultAddressBook(NABConnectionID id, NABAddrBookDescType **aBook); + +/* + * This call will create a local/personal address book with the name given. + * + * Return Value: + * NAB_SUCCESS - The personal address book was created successfully. + * NAB_FAILURE - General failure to create the address book + * NAB_NOT_OPEN - This will be returned when a call is made to the API without NAB_Open() being called first. + * NAB_PERMISSION_DENIED - User does not have write permission to create an address book + * NAB_DISK_FULL - Disk full condition encountered attempting to create address book + * NAB_INVALID_NAME - The name for the address book is invalid or already exists + * NAB_INVALID_ABOOK - Address book specified is invalid + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * addrBookName - the description name for the address book to be created + * addrBook - a pointer to the addrBook entry that will be populated by the API for the newly created API - if + * the create call fails, this pointer is set to NULL - + * [memory allocated by API and must be freed by a call to NAB_FreeMemory()] + */ +NABError NAB_CreatePersonalAddressBook(NABConnectionID id, char *addrBookName, NABAddrBookDescType **addrBook); + +/******************************************************** + * Memory Handling Calls + ********************************************************/ + +/* + * This call frees memory allocated by the NABAPI. + * + * Return Value: + * NAB_SUCCESS - The memory pointed to by ptr was freed successfully. + * NAB_FAILURE - The ptr parameter was NULL or was unable to be free'd + * + * Parameters: + * ptr - this is a pointer to the memory allocated by the NABAPI. + */ +NABError NAB_FreeMemory(void *ptr); + +/******************************************************** + * Utility Calls + ********************************************************/ + +/* + * This will save the address book specified by the addrBook parameter into a + * table formatted, HTML file. The fields to be saved should be passed into + * the call via the ldifFields parameter. + * + * Return Value: + * NAB_SUCCESS - The address book was saved to an HTML file. + * NAB_FAILURE - General failure to create save the address book + * NAB_NOT_OPEN - This will be returned when a call is made to the API + * without NAB_Open() being called first. + * NAB_PERMISSION_DENIED - User does not have write permission to create + * an address book + * NAB_DISK_FULL - Disk full condition encountered attempting to create address book + * NAB_INVALID_NAME - The name for the address book is invalid or already exists + * NAB_INVALID_ABOOK - Address book specified is invalid + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * addrBook - a pointer to a NABAddrBookDescType structure for the particular + * address book for the operation + * fileName - the name for the output HTML file on disk + */ +NABError NAB_SaveAddressBookToHTML(NABConnectionID id, NABAddrBookDescType *addrBook, + char *fileName); + +/* + * This call will import an LDIF formatted file from a disk file to the address + * book specified by the addrBook parameter. + * + * Return Value: + * NAB_SUCCESS - The import operation succeeded. + * NAB_FAILURE - General failure to during the import operation + * NAB_NOT_OPEN - This will be returned when a call is made to the API without + * NAB_Open() being called first. + * NAB_PERMISSION_DENIED - User does not have write permission to the address + * book or to read the import disk file + * NAB_DISK_FULL - Disk full condition encountered attempting to import the address book + * NAB_INVALID_ABOOK - Address book specified is invalid + * NAB_FILE_NOT_FOUND - The disk file was not found + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * addrBook - a pointer to a NABAddrBookDescType structure for the particular address + * book for the operation + * fileName - the disk file name for the import operation + * deleteFileWhenFinished - if this is true, the temp file will be deleted upon exit + */ +NABError NAB_ImportLDIFFile(NABConnectionID id, NABAddrBookDescType *addrBook, + char *fileName, NABBool deleteFileWhenFinished); + +/* + * This call will export the contents of an address book specified by the + * addrBook parameter to an LDIF formatted disk file. + * + * Return Value: + * NAB_SUCCESS - The export operation succeeded. + * NAB_FAILURE - General failure to during the export operation + * NAB_NOT_OPEN - This will be returned when a call is made to the API + * without NAB_Open() being called first. + * NAB_PERMISSION_DENIED - User does not have write permission for the output + * disk file + * NAB_DISK_FULL - Disk full condition encountered attempting to export the + * address book + * NAB_INVALID_ABOOK - Address book specified is invalid + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * addrBook - a pointer to a NABAddrBookDescType structure for the particular address book + * for the operation + * fileName - the disk file name for the export operation + */ +NABError NAB_ExportLDIFFile(NABConnectionID id, NABAddrBookDescType *addrBook, char *fileName); + +/* + * This is a convenience call that will format an LDIF string for use with calls such + * as NAB_InsertAddressBookEntry() and NAB_UpdateAddressBookEntry(). The memory for + * the line is allocated by the NAB_FormatLDIFLine() and must be freed by the caller + * with the NAB_FreeMemory() call. + * + * Return Value: + * NULL - the call failed for one of the following reasons: + * + * - There were not valid parameters passed into the call + * - The memory allocation failed + * + * char * - a pointer to the allocated string + * + * Parameters: + * firstName (sn) - persons first name + * lastName (givenname) - last name + * generalNotes (description) - general notes for entry + * city (locality) - City + * state (st) - State + * email (mail) - Email Address + * title (title) - Job Title or position + * addrLine1 (postOfficeBox) - Address line #1 + * addrLine2 (streetaddress) - Address line #2 + * zipCode (postalcode) - Zip Code + * country (countryname) - Country Name + * businessPhone (telephonenumber) - Business Telephone Number + * faxPhone (facsimiletelephonenumber) - FAX Number + * homePhone (homephone) - Home Phone Number + * organization (o) - Organization or company name + * nickname (xmozillanickname) - Communicator Nickname + * useHTML (xmozillausehtmlmail) - Preference for HTML composition + */ +char *NAB_FormatLDIFLine(char *firstName, + char *lastName, + char *generalNotes, + char *city, + char *state, + char *email, + char *title, + char *addrLine1, + char *addrLine2, + char *zipCode, + char *country, + char *businessPhone, + char *faxPhone, + char *homePhone, + char *organization, + char *nickname, + char *useHTML); + +/******************************************************** + * Individual Entry Calls + ********************************************************/ + +/* + * This call will get the User ID for the first person in the specified address + * book and it will also return the attributes for the user in the ldifEntry field. The memory for + * this field must be freed by a call to NAB_FreeMemory(). The addrBook argument is + * passed back via the calls that return NABAddrBookDescType structures. + * The call will also return the time this entry was last updated via the NABUpdateTime + * paramenter. The memory for this structure should be allocated by the + * calling application. It will return NAB_SUCCESS if an entry was found or NAB_NOT_FOUND + * if no entries are found. If a user is found, ID for the user returned is + * stored in the userID argument. + * + * Return Value: + * NAB_SUCCESS - The operation succeeded and an entry was found. + * NAB_FAILURE - General failure getting the first address book entry + * NAB_NOT_OPEN - This will be returned when a call is made to the API without + * NAB_Open() being called first. + * NAB_INVALID_ABOOK - Address book specified is invalid + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * addrBook - a pointer to a NABAddrBookDescType structure for the particular + * address book for the operation + * userID - a pointer to a NABUserID value that will be filled out by the API with the ID + * for the found user + * ldifEntry - the ldif formatted information for the found user [memory allocated by API + * and must be freed by a call to NAB_FreeMemory()] + * time - a pointer to the the NABUpdateTime value for the time of last update for the individual entry + */ +NABError NAB_GetFirstAddressBookEntry(NABConnectionID id, NABAddrBookDescType *addrBook, NABUserID *userID, + char **ldifEntry, NABUpdateTime *updTime); + +/* + * This call will get the next address book entry from the specified address book and it will also + * return the attributes for the user in the ldifEntry field. The memory for + * this field must be freed by a call to NAB_FreeMemory(). The addrBook argument is passed back + * via the calls that return NABAddrBookDescType structures. The call will also return the time this + * entry was last updated via the NABUpdateTime paramenter. The memory for this structure should be allocated by the + * calling application. It will return NAB_SUCCESS if an entry was found or NAB_NOT_FOUND if the + * final entry has already been returned. If a user is found, ID for the user returned is stored + * in the userID argument. + * + * Return Value: + * NAB_SUCCESS - The operation succeeded and the next entry was found. + * NAB_FAILURE - General failure getting the next address book entry + * NAB_NOT_FOUND - The final entry was already returned + * NAB_NOT_OPEN - This will be returned when a call is made to the API without NAB_Open() being called first. + * NAB_INVALID_ABOOK - NAB_GetFirstAddressBookEntry() probably wasn't called + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * userID - a pointer to a NABUserID value that will be filled out by the API with the ID for the found user + * ldifEntry - the ldif formatted information for the found user [memory allocated by API and must + * be freed by a call to NAB_FreeMemory()] + * time - a pointer to the the NABUpdateTime value for the time of last update for the individual entry + */ +NABError NAB_GetNextAddressBookEntry(NABConnectionID id, NABUserID *userID, + char **ldifEntry, NABUpdateTime *updTime); + +/* + * This call will perform a query on the specified ldif attribute pair. The memory for the ldifEntry + * will be allocated by the API and must be freed by a call to NAB_FreeMemory(). The addrBook argument + * is passed back via the calls that return NABAddrBookDescType structures. The call will also return the time + * this entry was last updated via the NABUpdateTime paramenter. The memory for this structure should be + * allocated by the calling application. It will return NAB_SUCCESS if an entry was found or NAB_NOT_FOUND + * if the search failed. + * + * Return Value: + * NAB_SUCCESS - The operation succeeded and the requested entry was found. + * NAB_FAILURE - General failure performing the query + * NAB_NOT_FOUND - The requested entry was not found + * NAB_NOT_OPEN - This will be returned when a call is made to the API without NAB_Open() being called first. + * NAB_INVALID_ABOOK - Address book specified is invalid + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * addrBook - a pointer to a NABAddrBookDescType structure for the particular address book for the operation + * ldifSearchAttribute - the attribute/value pairing for the search operation + * ldifEntry - the ldif formatted information for the user entry found [memory allocated by API and + * must be freed by a call to NAB_FreeMemory()] + * time - a pointer to the the NABUpdateTime value for the time of last update for the individual entry + */ +NABError NAB_FindAddressBookEntry(NABConnectionID id, NABAddrBookDescType *addrBook, + NABUserID *userID, char *ldifSearchAttribute, + char **ldifEntry, NABUpdateTime *updTime); + +/* + * This call will insert an individual address book entry (in LDIF format) into the (addrBookID) address + * book. The addrBook argument is passed back via the calls that return NABAddrBookDescType structures. + * If this user already exists in the specified address book, the operation will fail. + * + * Return Value: + * NAB_SUCCESS - The insert operation succeeded. + * NAB_FAILURE - General failure to during the insert operation + * NAB_NOT_OPEN - This will be returned when a call is made to the API without NAB_Open() being called first. + * NAB_PERMISSION_DENIED - User does not have write permission to the address book to perform the insertion operation + * NAB_DISK_FULL - Disk full condition encountered attempting to insert the entry into the address book + * NAB_INVALID_ABOOK - Address book specified is invalid + * NAB_ALREADY_EXISTS - The user entry already exists in the address book + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * addrBook - a pointer to a NABAddrBookDescType structure for the particular address book for the operation + * ldifEntry - the entry to be inserted into the identified address book + * userID - a pointer to a NABUserID value that will be filled out by the API with the ID for the new user + */ +NABError NAB_InsertAddressBookEntry(NABConnectionID id, NABAddrBookDescType *addrBook, char *ldifEntry, NABUserID *userID); + +/* This call will update the specified address book entry in the specified address book with the + * information passed in via the LDIF formatted entry. Attributes that exists will be replaced by the + * new entry and new attributes will be added to the user record. The addrBook argument is passed back + * via the calls that return NABAddrBookDescType structures. If the entry is not found, the call will fail. + * + * Return Value: + * NAB_SUCCESS - The update operation succeeded. + * NAB_FAILURE - General failure to during the update operation + * NAB_NOT_OPEN - This will be returned when a call is made to the API without NAB_Open() being called first. + * NAB_PERMISSION_DENIED - User does not have write permission to the address book to perform the update operation + * NAB_DISK_FULL - Disk full condition encountered attempting to update the entry into the address book + * NAB_INVALID_ABOOK - Address book specified is invalid + * NAB_NOT_FOUND - The user entry to update does not exist in the address book + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * addrBook - a pointer to a NABAddrBookDescType structure for the particular address book for the operation + * userID - the specific user ID for the entry to be updated + * ldifEntry - the attribute pairs to be updated in the identified address book + */ +NABError NAB_UpdateAddressBookEntry(NABConnectionID id, NABAddrBookDescType *addrBook, NABUserID userID, + char *ldifEntry); + +/* + * This call will delete the specified address book entry in the specified address book. The addrBook + * argument is passed back via the calls that return NABAddrBookDescType structures. If the entry is + * not found, the call will fail. + * + * Return Value: + * NAB_SUCCESS - The delete operation succeeded. + * NAB_FAILURE - General failure to during the delete operation + * NAB_NOT_OPEN - This will be returned when a call is made to the API without NAB_Open() being called first. + * NAB_PERMISSION_DENIED - User does not have write permission to the address book to perform the delete operation + * NAB_DISK_FULL - Disk full condition encountered attempting to delete the entry into the address book + * NAB_INVALID_ABOOK - Address book specified is invalid + * NAB_NOT_FOUND - The user entry to delete does not exist in the address book + * + * Parameters: + * id - the connection ID returned by the NAB_Open() call + * addrBook - a pointer to a NABAddrBookDescType structure for the particular address book for the operation + * userID - the specific user ID for the entry to be updated + */ +NABError NAB_DeleteAddressBookEntry(NABConnectionID id, NABAddrBookDescType *addrBook, NABUserID userID); + + +#endif // ifdef __NABAPI_H__