Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-10-31 14:15:30 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
a1cde307de
gecko-dev/cmd/winfe/nabapi.h
spider cb94dae31e NORMANDY_DDAY merge...
1998-06-25 05:50:45 +00:00

492 lines
24 KiB
C
Raw Blame History

/* -*- 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__
Reference in New Issue View Git Blame Copy Permalink