mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-06 12:43:53 +00:00
61a97fd94a
r='s from many people. sr=jst
2642 lines
115 KiB
C
2642 lines
115 KiB
C
/* -*- 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.
|
|
*/
|
|
|
|
/* file: abtable.h
|
|
** Some portions derive from public domain IronDoc code and interfaces.
|
|
**
|
|
** This is the public address book interface that should be included by
|
|
** clients that want to access address book content without knowing any
|
|
** more details than necessary about the internal implementation. This
|
|
** interface deliberately hides details concerning how this database
|
|
** independent layer can be targeted by third parties by subclassing.
|
|
**
|
|
** The private address book interface is specified in abmodel.h, which
|
|
** defines the interfaces of classes that allow third parties to target
|
|
** the address book interface by subclassing appropriate classes in the
|
|
** address book model. The private interface defines the structure and
|
|
** polymorphic vtables (if needed) for any classes in the public interface
|
|
** whose structure is hidden. If the public interface is constrained to
|
|
** call "factory" methods to construct and generate objects needed to
|
|
** access address book content, then under the covers these objects might
|
|
** be dynamically bound subclasses appropriate for use in a given model.
|
|
**
|
|
** Changes:
|
|
** <0> 22Oct1997 first draft
|
|
*/
|
|
|
|
#ifndef _ABTABLE_
|
|
#define _ABTABLE_ 1
|
|
|
|
/* ----- ----- ----- ----- switches ----- ----- ----- ----- */
|
|
|
|
#define AB_CONFIG_MACINTOSH /*i*/ 1
|
|
|
|
/* #define AB_CONFIG_UNIX 1 */ /*i*/
|
|
/* #define AB_CONFIG_WINDOWS 1 */ /*i*/
|
|
|
|
/*#define AB_CONFIG_LOGGING 1 */
|
|
|
|
/* #define AB_CONFIG_MOZ_NEWADDR 1 */ /*i*/
|
|
|
|
#ifdef AB_CONFIG_MOZ_NEWADDR
|
|
#define AB_CONFIG_SMALLER_INDEXES 1 /* use new smaller indexes */
|
|
#define AB_CONFIG_FIRST_LAST_INDEXES 1 /* use new name indexes */
|
|
#define AB_CONFIG_TUPLE_ENTRY 1 /* use new tuple entry class */
|
|
#endif /*AB_CONFIG_MOZ_NEWADDR*/
|
|
|
|
#define AB_CONFIG_USE_NEO_CACHE_TABLES 1 /*i*/
|
|
|
|
#define AB_CONFIG_TRUNCATE_FULL_NAME 1 /* force rather short */
|
|
|
|
/*#define AB_CONFIG_ENABLE_INDEX_REFRESH 1*/ /* allow */
|
|
|
|
#define AB_CONFIG_DEBUG /*i*/ 1
|
|
|
|
#ifdef AB_CONFIG_DEBUG
|
|
#define AB_CONFIG_PRINT /*i*/ 1
|
|
#endif
|
|
|
|
#ifdef AB_CONFIG_DEBUG
|
|
#define AB_CONFIG_TRACE /*i*/ 1
|
|
#endif
|
|
|
|
#ifdef AB_CONFIG_DEBUG
|
|
#define AB_CONFIG_MAXIMIZE_FEATURES /*i*/ 1
|
|
#endif
|
|
|
|
#ifdef AB_CONFIG_TRACE
|
|
#define AB_CONFIG_TRACE_CALL_TREE /*i*/ 1
|
|
#else
|
|
#define AB_CONFIG_TRACE_CALL_TREE 0
|
|
#endif
|
|
|
|
#if defined(AB_CONFIG_TRACE) || defined(AB_CONFIG_DEBUG) \
|
|
|| defined(AB_CONFIG_PRINT)
|
|
#define AB_CONFIG_TRACE_orDEBUG_orPRINT /*i*/ 1
|
|
#else
|
|
#define AB_CONFIG_TRACE_orDEBUG_orPRINT 0
|
|
#endif
|
|
|
|
#if defined(AB_CONFIG_TRACE) || defined(AB_CONFIG_LOGGING)
|
|
#define AB_CONFIG_TRACE_andLOGGING /*i*/ 1
|
|
#else
|
|
#define AB_CONFIG_TRACE_andLOGGING 0
|
|
#endif
|
|
|
|
#ifdef AB_CONFIG_DEBUG
|
|
#define AB_CONFIG_KNOW_FAULT_STRINGS 1
|
|
#endif
|
|
|
|
/* ----- ----- ----- disable unused param warnings ----- ----- ----- */
|
|
|
|
#define AB_USED_PARAMS_1(x) (void)(&x)
|
|
#define AB_USED_PARAMS_2(x,y) (void)(&x,&y)
|
|
#define AB_USED_PARAMS_3(x,y,z) (void)(&x,&y,&z)
|
|
#define AB_USED_PARAMS_4(w,x,y,z) (void)(&w,&x,&y,&z)
|
|
|
|
/* ----- ----- ----- assertions ----- ----- ----- */
|
|
|
|
#define AB_ASSERT(x) XP_ASSERT(x)
|
|
|
|
/* ----- ----- ----- utilities ----- ----- ----- */
|
|
|
|
#define AB_MEMCPY(dest,src,size) XP_MEMCPY(dest,src,size)
|
|
#define AB_MEMMOVE(dest,src,size) XP_MEMMOVE(dest,src,size)
|
|
#define AB_MEMSET(dest,byte,size) XP_MEMSET(dest,byte,size)
|
|
#define AB_STRCPY(dest,src) XP_STRCPY(dest,src)
|
|
#define AB_STRCAT(dest,src) XP_STRCAT(dest,src)
|
|
#define AB_STRCMP(one,two) XP_STRCMP(one,two)
|
|
#define AB_STRNCMP(one,two,length) XP_STRNCMP(one,two,length)
|
|
#define AB_STRLEN(string) XP_STRLEN(string)
|
|
|
|
/*3456789_123456789_123456789_123456789_123456789_123456789_123456789_12345678*/
|
|
/* ----- ----- ----- ----- signatures ----- ----- ----- ----- */
|
|
|
|
#include "xp_core.h"
|
|
#include "xp.h"
|
|
|
|
#if defined(XP_CPLUSPLUS)
|
|
# define AB_BEGIN_C_PROTOS extern "C" {
|
|
# define AB_END_C_PROTOS }
|
|
#else
|
|
# define AB_BEGIN_C_PROTOS
|
|
# define AB_END_C_PROTOS
|
|
#endif
|
|
|
|
#define AB_PUBLIC_API(returnType) /*i*/ returnType
|
|
/* API() wraps return types of header file library public methods */
|
|
|
|
#define AB_API_IMPL(returnType) returnType
|
|
/* API_IMPL() wraps return types of .c file library public methods */
|
|
|
|
#define AB_MODEL(returnType) /*i*/ returnType
|
|
/* MODEL() wraps return types of header file semi-private model methods */
|
|
|
|
#define AB_MODEL_IMPL(returnType) returnType
|
|
/* MODEL_IMPL() wraps return types of .c file semi-private model methods */
|
|
|
|
#define AB_LIB(returnType) /*i*/ returnType
|
|
/* LIB() wraps return types of header file library private methods */
|
|
|
|
#define AB_LIB_IMPL(returnType) /*i*/ returnType
|
|
/* LIB_IMPL() wraps return types of .c file library private methods */
|
|
|
|
#define AB_FILE_IMPL(returnType) static returnType
|
|
/* FILE_IMPL() wraps return types of .c file scoped methods */
|
|
|
|
/* ----- ----- ----- ----- primitives ----- ----- ----- ----- */
|
|
|
|
#ifdef AB_BOOL_STAND_ALONE
|
|
|
|
typedef unsigned char ab_bool /*d*/; /* any nonzero value implies true */
|
|
#define AB_kFalse /*i*/ 0
|
|
#define AB_kTrue /*i*/ 1
|
|
|
|
#else /* else ! AB_BOOL_STAND_ALONE ------- */
|
|
|
|
#include "xp_core.h"
|
|
typedef XP_Bool ab_bool; /* boolean */
|
|
#define AB_kFalse FALSE
|
|
#define AB_kTrue TRUE
|
|
|
|
#endif /* end AB_BOOL_STAND_ALONE ------- */
|
|
|
|
typedef unsigned char ab_u1 /*d*/; /* unsigned 1 byte */
|
|
|
|
typedef short ab_i2 /*d*/; /* signed 2 bytes */
|
|
typedef unsigned short ab_u2 /*d*/; /* unsigned 2 bytes */
|
|
|
|
typedef long ab_i4 /*d*/; /* signed 4 bytes */
|
|
typedef unsigned long ab_u4 /*d*/; /* unsigned 4 bytes */
|
|
|
|
typedef ab_u4 ab_num /*d*/; /* a "count" with many bits */
|
|
typedef ab_u4 ab_pos /*d*/; /* an index "position" with many bits */
|
|
typedef ab_u4 ab_uid /*d*/; /* a unique id with many bits */
|
|
|
|
typedef ab_i4 ab_map_int /*d*/; /* size must be at least sizeof(void*) */
|
|
typedef ab_u4 ab_policy /*d*/; /* generally to hold policy enum values */
|
|
|
|
/* ----- ----- ----- ----- forwards ----- ----- ----- ----- */
|
|
|
|
#ifndef AB_Fault_typedef
|
|
typedef struct AB_Fault AB_Fault;
|
|
#define AB_Fault_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_PosPair_typedef
|
|
typedef struct AB_PosPair AB_PosPair;
|
|
#define AB_PosPair_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_PosRange_typedef
|
|
typedef struct AB_PosRange AB_PosRange;
|
|
#define AB_PosRange_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Env_typedef
|
|
typedef struct AB_Env AB_Env;
|
|
#define AB_Env_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Sink_typedef
|
|
typedef struct AB_Sink AB_Sink;
|
|
#define AB_Sink_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Debugger_typedef
|
|
typedef struct AB_Debugger AB_Debugger;
|
|
#define AB_Debugger_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Tracer_typedef
|
|
typedef struct AB_Tracer AB_Tracer;
|
|
#define AB_Tracer_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Table_typedef
|
|
typedef struct AB_Table AB_Table;
|
|
#define AB_Table_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_AsyncTask_typedef
|
|
typedef struct AB_AsyncTask AB_AsyncTask;
|
|
#define AB_AsyncTask_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_AsyncResult_typedef
|
|
typedef struct AB_AsyncResult AB_AsyncResult;
|
|
#define AB_AsyncResult_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Column_typedef
|
|
typedef struct AB_Column AB_Column;
|
|
#define AB_Column_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Row_typedef
|
|
typedef struct AB_Row AB_Row;
|
|
#define AB_Row_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Cell_typedef
|
|
typedef struct AB_Cell AB_Cell;
|
|
#define AB_Cell_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Store_typedef
|
|
typedef struct AB_Store AB_Store;
|
|
#define AB_Store_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_Thumb_typedef
|
|
typedef struct AB_Thumb AB_Thumb;
|
|
#define AB_Thumb_typedef 1
|
|
#endif
|
|
|
|
#ifndef AB_File_typedef
|
|
typedef struct AB_File AB_File;
|
|
#define AB_File_typedef 1
|
|
#endif
|
|
|
|
#ifndef DIR_Server_typedef
|
|
typedef struct DIR_Server DIR_Server;
|
|
#define DIR_Server_typedef 1
|
|
#endif
|
|
|
|
/* ----- ----- ----- ----- types ----- ----- ----- ----- */
|
|
|
|
typedef ab_u4 ab_ref_count; /* counts times any object is acquired */
|
|
/*- This reference count is needed for tables and might be used by other
|
|
runtime objects as well. A reference count is a runtime session effect and
|
|
not a persistent value. Nothing stored persistently in a database implies
|
|
anything about runtime reference counts. -*/
|
|
|
|
#define AB_Fault_kNone 0 /* zero means no error */
|
|
/*- No error unique id uses the value of zero. -*/
|
|
|
|
typedef ab_i4 ab_error_uid; /* unique id for an error */
|
|
/*- Unique id for an error specific to address books.
|
|
Zero means no error. -*/
|
|
|
|
typedef ab_num ab_error_count; /* numeric count of errors */
|
|
/*- Type that clearly counts errors. -*/
|
|
|
|
typedef ab_num ab_count; /* numeric count of something */
|
|
typedef ab_num ab_uid_count; /* numeric count of uids */
|
|
typedef ab_pos ab_uid_pos; /* array index for individual uid */
|
|
|
|
typedef ab_uid ab_db_uid; /* unique id from a database */
|
|
/*- A db uid is a unique id generated by a database, which need not
|
|
follow any conventions used by address books. The unique ids used by
|
|
address books for rows and columns are constructed from database uids
|
|
by bitshifting the db uids and ORing in tag bits that distinguish
|
|
various kinds of address book unique ids. This db uid type is intended
|
|
to explicitly indicate that tag bits are not present as understood by
|
|
address books, and that bitshifting and other transformations are needed
|
|
to convert between db uids and other kinds of uids. -*/
|
|
|
|
typedef ab_db_uid ab_db_index_uid; /* unique id for db index */
|
|
typedef ab_db_uid ab_db_name_uid; /* unique id for db name token */
|
|
typedef ab_db_uid ab_db_set_uid; /* unique id for db set of things */
|
|
typedef ab_db_set_uid ab_db_list_set_uid; /* uid for db set of lists */
|
|
typedef ab_db_uid ab_db_row_uid; /* unique id for db row */
|
|
typedef ab_db_row_uid ab_db_parent_uid; /* uid for parent db row */
|
|
typedef ab_db_row_uid ab_db_child_uid; /* uid for child db row */
|
|
|
|
typedef ab_db_uid ab_db_list_uid; /* unique id for db row with children */
|
|
typedef ab_num ab_list_count; /* numeric count of lists */
|
|
typedef ab_pos ab_list_pos; /* array index for individual list */
|
|
|
|
typedef ab_uid ab_row_uid; /* unique id for a row */
|
|
typedef ab_uid ab_column_uid; /* unique id for a column */
|
|
/*- Row and column unique ids have address book scope, so all tables
|
|
inside a single address book share the same unique id name space for
|
|
rows and columns. There need not be a unique id type for tables
|
|
because all tables are alwo rows. -*/
|
|
|
|
typedef ab_uid ab_model_uid; /* unique id for a model */
|
|
typedef ab_uid ab_store_uid; /* unique id for a store */
|
|
|
|
typedef ab_row_uid ab_table_uid; /* unique id for a table */
|
|
typedef ab_table_uid ab_container_uid; /* unique id for database container */
|
|
|
|
typedef ab_num ab_row_count; /* numeric count of rows */
|
|
typedef ab_num ab_column_count; /* numeric count of columns */
|
|
/*- These types help clarify when integer values are intended to count
|
|
differnt kinds of objects. -*/
|
|
|
|
typedef ab_pos ab_row_pos; /* array index for individual row */
|
|
typedef ab_pos ab_column_pos; /* array index for individual column */
|
|
typedef ab_pos ab_cell_pos; /* array index for individual cell */
|
|
/*- These types help clarify when integer values are intended to specifiy
|
|
an array position within an ordered sequence of rows, columns, or cells.
|
|
Currently row and column positions are one-based so zero can be
|
|
reserved to mean an exceptional condition. -*/
|
|
|
|
/* `````` `````` protos `````` `````` */
|
|
AB_BEGIN_C_PROTOS
|
|
/* `````` `````` protos `````` `````` */
|
|
|
|
/* ----- ----- ----- ----- position sets ----- ----- ----- ----- */
|
|
|
|
struct AB_PosPair /*d*/ {
|
|
ab_pos sPosPair_First; /* first position in a sequence */
|
|
ab_pos sPosPair_Last; /* last position in a sequence */
|
|
};
|
|
|
|
|
|
#if AB_CONFIG_TRACE_orDEBUG_orPRINT
|
|
AB_PUBLIC_API(char*) /* abtable.cpp */
|
|
AB_PosPair_AsXmlString(const AB_PosPair* self, char* outXmlBuf);
|
|
/* <ab:pos:pair first="%lu" last="%lu"/> */
|
|
#endif /*AB_CONFIG_TRACE_orDEBUG_orPRINT*/
|
|
|
|
struct AB_PosRange /*d*/ {
|
|
ab_pos sPosRange_First; /* first position in a sequence */
|
|
ab_count sPosRange_Count; /* number of positions in sequence */
|
|
};
|
|
|
|
#if AB_CONFIG_TRACE_orDEBUG_orPRINT
|
|
AB_PUBLIC_API(char*) /* abtable.cpp */
|
|
AB_PosRange_AsXmlString(const AB_PosRange* self, char* outXmlBuf);
|
|
/* <ab:pos:range first="%lu" count="%lu"/> */
|
|
#endif /*AB_CONFIG_TRACE_orDEBUG_orPRINT*/
|
|
|
|
/* ----- ----- ----- ----- Unique Ids ----- ----- ----- ----- */
|
|
|
|
#define AB_Bit_kTempBit ( 1 << 0 ) /* 2^0 bit: not persistent */
|
|
#define AB_Bit_kGlobalBit ( 1 << 1 ) /* 2^1 bit: global if also temp */
|
|
#define AB_Bit_kColumnBit ( 1 << 1 ) /* 2^1 bit: column if also persistent */
|
|
#define AB_Bit_kStandardBit ( 1 << 2 ) /* 2^2 bit: uid is standard constant */
|
|
#define AB_Uid_kGlobal ( AB_Bit_kGlobalBit | AB_Bit_kTempBit )
|
|
#define AB_Uid_kColumn AB_Bit_kColumnBit
|
|
#define AB_Uid_kPersistentRow 0
|
|
#define AB_Uid_kStandardColumn ( AB_Bit_kColumnBit | AB_Bit_kStandardBit )
|
|
#define AB_Uid_kTagBitCount 3
|
|
#define AB_Bit_kLowTwoBits 0x3
|
|
#define AB_Bit_kLowThreeBits 0x7
|
|
/*- These constants define bit patterns used to encode unique ids to
|
|
determine the purpose of a specific uids. Unique ids which are only
|
|
meaningful during a single session are called temporary or transient
|
|
(as opposed to persistent). Transient uids are to global tables and to
|
|
tables generated dynamically to describe the results of queries or
|
|
searches.
|
|
|
|
The column bit and the global bit are the same bit because there is no
|
|
overlap in practical usage, because columns are never transient, and
|
|
globals are always transient. (We want to use as few bits for encoding as
|
|
possible because this reserves most of the bits for a larger name space
|
|
for uids. Using only two bits leaves 30 bits for 2^30 distinct persistent
|
|
ids in a db.) -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
#define AB_Uid_IsTransient(uid) ((uid) & AB_Bit_kTempBit)
|
|
/*- IsTransientId indicates whether a uid is transient (not persistent)
|
|
withmeaning only during the current session. -*/
|
|
|
|
#define AB_Uid_IsGlobal(uid) (((uid) & AB_Bit_kLowTwoBits) == AB_Uid_kGlobal)
|
|
/*- IsGlobal indicates whether a uid is the transient uid assigned to a
|
|
globaltable for a personal address book or an LDAP directory. -*/
|
|
|
|
#define AB_Uid_IsPersistent(uid) (((uid) & AB_Bit_kTempBit) == 0)
|
|
/*- IsPersistent indicates whether a uid has meaning across multiple
|
|
sessions because a database persistently associates this uid with some
|
|
entity. -*/
|
|
|
|
#define AB_Uid_IsPersistentRow(uid) \
|
|
(((uid) & AB_Bit_kLowTwoBits) == AB_Uid_kPersistentRow)
|
|
|
|
#define AB_Uid_IsRow(uid) \
|
|
(((uid) & AB_Bit_kLowTwoBits) != AB_Uid_kColumn)
|
|
/*- IsRow indicates whether a uid denotes a row. This includes both
|
|
transient and persistent rows. Basically anything not a column is a row.
|
|
All tables are considered rows, including address books and directories. -*/
|
|
|
|
#define AB_Uid_IsColumn(uid) \
|
|
(((uid) & AB_Bit_kLowTwoBits) == AB_Uid_kColumn)
|
|
/*- IsColumn indicates whether a uid denotes a column. Column uids are
|
|
always peristent and have a non-overlapping scope only inside specific
|
|
address books. That is, all column uids for a given address book are
|
|
unique, but different address books can use the same column uids to
|
|
mean different column names. -*/
|
|
|
|
#define AB_Uid_IsStandard(uid) \
|
|
(((uid) & AB_Bit_kStandardBit) != 0)
|
|
|
|
#define AB_Uid_IsStandardColumn(uid) \
|
|
(((uid) & AB_Bit_kLowThreeBits) == AB_Uid_kStandardColumn)
|
|
|
|
|
|
#define AB_Attrib_AsStdColUid(attrib) \
|
|
(( ((ab_column_uid) attrib) << AB_Uid_kTagBitCount) | AB_Uid_kStandardColumn)
|
|
|
|
#define AB_ColumnUid_AsAttrib(uid) \
|
|
( (AB_Uid_IsStandard(uid))? ( (uid) >> AB_Uid_kTagBitCount ) : 0 )
|
|
|
|
#define AB_DbUid_AsColumnUid(uid) \
|
|
(( (uid) << AB_Uid_kTagBitCount) | AB_Uid_kColumn)
|
|
|
|
#define AB_ColumnUid_AsDbUid(uid) \
|
|
( (AB_Uid_IsColumn(uid))? ( (uid) >> AB_Uid_kTagBitCount ) : 0 )
|
|
|
|
#define AB_UidSeed_AsTempRowUid(uid) \
|
|
( ((uid) << AB_Uid_kTagBitCount) | AB_Bit_kTempBit )
|
|
|
|
#define AB_DbUid_AsRowUid(uid) \
|
|
( (uid) << AB_Uid_kTagBitCount )
|
|
|
|
#define AB_RowUid_AsDbUid(uid) \
|
|
( (AB_Uid_IsRow(uid))? ( (uid) >> AB_Uid_kTagBitCount ) : 0 )
|
|
|
|
#define AB_PersistentRowUid_AsDbUid(uid) \
|
|
( (AB_Uid_IsPersistentRow(uid))? ( (uid) >> AB_Uid_kTagBitCount ) : 0 )
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
typedef ab_num ab_cell_length; /* amount of cell content in AB_Row */
|
|
/*- This number characterizes the length of content bytes in a AB_Row,
|
|
buffered in memory, and is typically less than ab_cell_size. In other
|
|
words this is the length of content stored in memory, as opposed to the
|
|
extent (which is persistent content size). -*/
|
|
|
|
typedef ab_num ab_cell_extent; /* amount of cell content in table row */
|
|
/*- This number characterizes the persistent size of content in a row's
|
|
cell inside a table. This is the persistent idea content length but which
|
|
might be greater than ab_cell_length when a memory buffer is not big
|
|
enough to hold the persistent value. -*/
|
|
|
|
typedef ab_num ab_cell_size; /* bytes for a cell in row column */
|
|
/*- This number characterizes a number of bytes of space used to buffer a
|
|
row's cell value. This is independent of either length or extent. -*/
|
|
|
|
typedef ab_num ab_cell_count; /* number of cells in a row */
|
|
/*- This is a number of cells inside a row. -*/
|
|
|
|
/*3456789_123456789_123456789_123456789_123456789_123456789_123456789_12345678*/
|
|
|
|
/* ----- ----- ----- ----- Fault ----- ----- ----- ----- */
|
|
|
|
#define AB_Fault_kErrnoSpace /*i*/ 0x65526E4F /* ASCII 'eRnO' */
|
|
#define AB_Fault_kAbookSpace /*i*/ 0x61426752 /* ASCII 'aBgR' (no endian) */
|
|
|
|
/* AB_Fault structure and interface derive from public domain IronDoc */
|
|
|
|
struct AB_Fault /*d*/ {
|
|
ab_error_uid sFault_Code;
|
|
ab_u4 sFault_Space;
|
|
};
|
|
|
|
#define AB_Fault_Clear(f) /*i*/ \
|
|
((f)->sFault_Code = 0, (f)->sFault_Space = 0)
|
|
|
|
#define AB_Fault_Assign(e,other) /*i*/ (*(e) = *(other))
|
|
|
|
#define AB_Fault_Init(f,c,s) /*i*/ \
|
|
((f)->sFault_Code = (c), (f)->sFault_Space = (s))
|
|
|
|
#define AB_Fault_Code(f) /*i*/ ((f)->sFault_Code)
|
|
#define AB_Fault_Space(f) /*i*/ ((f)->sFault_Space)
|
|
|
|
enum AB_Fault_ePartition { /* number ranges for AB classes and features */
|
|
AB_Fault_kErrno = 0, /*i*/
|
|
AB_Fault_kErrno_end = 99, /*i*/
|
|
|
|
AB_Fault_kEnv = 100, /*i*/
|
|
AB_Fault_kEnv_end = 149, /*i*/
|
|
|
|
AB_Fault_kObject = 150, /*i*/
|
|
AB_Fault_kObject_end = 199, /*i*/
|
|
|
|
AB_Fault_kTable = 200, /*i*/
|
|
AB_Fault_kTable_end = 299, /*i*/
|
|
|
|
AB_Fault_kRow = 300, /*i*/
|
|
AB_Fault_kRow_end = 349, /*i*/
|
|
|
|
AB_Fault_kColumn = 350, /*i*/
|
|
AB_Fault_kColumn_end = 399, /*i*/
|
|
|
|
AB_Fault_kFile = 400, /*i*/
|
|
AB_Fault_kFile_end = 449, /*i*/
|
|
|
|
AB_Fault_kEntry = 450, /*i*/
|
|
AB_Fault_kEntry_end = 499, /*i*/
|
|
|
|
AB_Fault_kCell = 500, /*i*/
|
|
AB_Fault_kCell_end = 549, /*i*/
|
|
|
|
AB_Fault_kView = 550, /*i*/
|
|
AB_Fault_kView_end = 574, /*i*/
|
|
|
|
AB_Fault_kModel = 575, /*i*/
|
|
AB_Fault_kModel_end = 599, /*i*/
|
|
|
|
AB_Fault_kPort = 600, /*i*/
|
|
AB_Fault_kPort_end = 624, /*i*/
|
|
|
|
AB_Fault_kMap = 625, /*i*/
|
|
AB_Fault_kMap_end = 649, /*i*/
|
|
|
|
AB_Fault_kPart = 650, /*i*/
|
|
AB_Fault_kPart_end = 674, /*i*/
|
|
|
|
AB_Fault_kRowSet = 675, /*i*/
|
|
AB_Fault_kRowSet_end = 699, /*i*/
|
|
|
|
AB_Fault_kDebugger = 700, /*i*/
|
|
AB_Fault_kDebugger_end = 724, /*i*/
|
|
|
|
AB_Fault_kPrinter = 725, /*i*/
|
|
AB_Fault_kPrinter_end = 749, /*i*/
|
|
|
|
AB_Fault_kTracer = 750, /*i*/
|
|
AB_Fault_kTracer_end = 774, /*i*/
|
|
|
|
AB_Fault_kObjectSet = 775, /*i*/
|
|
AB_Fault_kObjectSet_end = 799, /*i*/
|
|
|
|
AB_Fault_kTuple = 800, /*i*/
|
|
AB_Fault_kTuple_end = 849, /*i*/
|
|
|
|
AB_Fault_kSearch = 850, /*i*/
|
|
AB_Fault_kSearch_end = 874, /*i*/
|
|
|
|
AB_Fault_kString = 875, /*i*/
|
|
AB_Fault_kString_end = 899, /*i*/
|
|
|
|
AB_Fault_kStore = 900, /*i*/
|
|
AB_Fault_kStore_end = 924, /*i*/
|
|
|
|
AB_Fault_kRowContent = 925, /*i*/
|
|
AB_Fault_kRowContent_end = 949 /*i*/
|
|
};
|
|
|
|
enum {
|
|
AB_Entry_kFaultDuplicateNickname = /*i*/ AB_Fault_kEntry, /* 450 */
|
|
AB_Entry_kFaultNotPersonType, /*i*/ /* 451 */
|
|
AB_Entry_kFaultNotListType, /*i*/ /* 452 */
|
|
AB_Entry_kFaultNotListOrPersonType, /*i*/ /* 453 */
|
|
AB_Entry_kFaultMissingGivenName, /*i*/ /* 454 */
|
|
AB_Entry_kFaultMissingEmailAddress, /*i*/ /* 455 */
|
|
AB_Entry_kFaultDuplicateEmail, /*i*/ /* 456 */
|
|
AB_Entry_kFaultNoSuchRowUid, /*i*/ /* 457 */
|
|
AB_Entry_kFaultNotFoundByIter, /*i*/ /* 458 */
|
|
AB_Entry_kFaultMissingFullName /*i*/ /* 459 */
|
|
};
|
|
|
|
AB_PUBLIC_API(const char*) /* abfault.c */
|
|
AB_Fault_String(const AB_Fault* self);
|
|
/* Return a static string describing error e, provided the space is equal
|
|
* to either AB_Fault_kErrnoSpace or AB_Fault_kAbookSpace,
|
|
* and provided AB_CONFIG_KNOW_FAULT_STRINGS is
|
|
* defined. Otherwise returns a static string for "{unknown-fault-space}"
|
|
* or for "{no-fault-strings}".
|
|
*/
|
|
|
|
#define AB_Fault_kXmlBufSize /*i*/ 128 /* size AB_Fault_AsXmlString() needs */
|
|
|
|
#if AB_CONFIG_TRACE_orDEBUG_orPRINT
|
|
AB_PUBLIC_API(char*) /* abfault.c */
|
|
AB_Fault_AsXmlString(const AB_Fault* self, AB_Env* ev, char* outXmlBuf);
|
|
/* <ab:fault string=\"%.32s\" code=\"#%08lX\" space =\"#%08lX/%.4s\"/> */
|
|
#endif /* end AB_CONFIG_TRACE_orDEBUG_orPRINT*/
|
|
|
|
#ifdef AB_CONFIG_DEBUG
|
|
AB_PUBLIC_API(void) /* abfault.c */
|
|
AB_Fault_Break(const AB_Fault* self, AB_Env* ev);
|
|
/* e.g. AB_Env_Break(ev, AB_Fault_AsXmlString(self, ev, buf)); */
|
|
#endif /*AB_CONFIG_DEBUG*/
|
|
|
|
#ifdef AB_CONFIG_TRACE
|
|
AB_PUBLIC_API(void) /* abfault.c */
|
|
AB_Fault_Trace(const AB_Fault* eself, AB_Env* ev);
|
|
/* e.g. AB_Env_Trace(ev, AB_Fault_AsXmlString(self, ev, buf)); */
|
|
#endif /*AB_CONFIG_TRACE*/
|
|
|
|
/* ----- ----- ----- ----- Env ----- ----- ----- ----- */
|
|
|
|
|
|
#ifndef AB_Env_typedef
|
|
typedef struct AB_Env AB_Env;
|
|
#define AB_Env_typedef 1
|
|
#endif
|
|
|
|
#define AB_Env_kFormatBufferSize /*i*/ 512 /* for var arg format methods */
|
|
|
|
/* AB_Env structures and interfaces derive from public domain IronDoc */
|
|
|
|
/*3456789_123456789_123456789_123456789_123456789_123456789_123456789_12345678*/
|
|
|
|
enum AB_Policy_eImportConflicts {
|
|
AB_Policy_ImportConflicts_kUnknown = 0, /* need to call policy method */
|
|
AB_Policy_ImportConflicts_kSignalError, /* AB_Env_kFaultImportDuplicate */
|
|
AB_Policy_ImportConflicts_kIgnoreNewDuplicates, /* quietly ignore new */
|
|
AB_Policy_ImportConflicts_kReportAndIgnore, /* report, then ignore */
|
|
AB_Policy_ImportConflicts_kReplaceOldWithNew, /* use new entry defn */
|
|
AB_Policy_ImportConflicts_kReportAndReplace, /* report, then replace */
|
|
AB_Policy_ImportConflicts_kUpdateOldWithNew, /* merge new entry defn */
|
|
AB_Policy_ImportConflicts_kReportAndUpdate, /* report, then merge */
|
|
|
|
/* default: report conflicts (to file "ab.import.conflicts") and ignore */
|
|
AB_Policy_ImportConflicts_kDefault =
|
|
AB_Policy_ImportConflicts_kIgnoreNewDuplicates,
|
|
|
|
AB_Policy_ImportConflicts_kMax =
|
|
AB_Policy_ImportConflicts_kReportAndUpdate
|
|
};
|
|
|
|
#define AB_Env_kConflictReportFileNameSize 256 /* plus one byte for end null */
|
|
|
|
typedef ab_policy (* AB_Env_mImportConflictPolicy /*d*/)
|
|
(AB_Env* ev, char* outReportFileName256); /* only 255 bytes for file name */
|
|
|
|
struct AB_Env /*d*/ {
|
|
ab_num sEnv_FaultCount; /* total number of stored faults */
|
|
|
|
ab_bool sEnv_DoTrace;
|
|
ab_bool sEnv_DoDebug;
|
|
ab_bool sEnv_DoErrBreak;
|
|
ab_bool sEnv_BeParanoid;
|
|
|
|
/* ````` callbacks (slots similar to polymorphic object vtable) ````` */
|
|
|
|
AB_Env_mImportConflictPolicy sEnv_ImportConflictPolicy;
|
|
};
|
|
|
|
#define AB_Env_Good(ev) /*i*/ ((ev)->sEnv_FaultCount == 0)
|
|
#define AB_Env_Bad(ev) /*i*/ ((ev)->sEnv_FaultCount != 0)
|
|
#define AB_Env_DoTrace(ev) /*i*/ ((ev)->sEnv_DoTrace)
|
|
|
|
enum AB_Env_eError {
|
|
AB_Env_kFaultNullMethods = /*i*/ AB_Fault_kEnv, /* 100 null vtable pointer */
|
|
AB_Env_kFaultWrongMethodTag, /*i*/ /* 101 vtable tag is wrong */
|
|
|
|
AB_Env_kFaultNullCheckStack, /*i*/ /* 102 missing CheckStack() method */
|
|
AB_Env_kFaultNullFree, /*i*/ /* 103 missing Free() method */
|
|
AB_Env_kFaultNullForgetErrors, /*i*/ /* 104 missing ForgetErrors() method */
|
|
|
|
AB_Env_kFaultNullErrorCount, /*i*/ /* 105 missing ErrorCount() method */
|
|
AB_Env_kFaultNullGetError, /*i*/ /* 106 missing GetError() method */
|
|
AB_Env_kFaultNullGetAllErrors, /*i*/ /* 107 missing GetAllErrors() method */
|
|
AB_Env_kFaultNullNewFault, /*i*/ /* 108 missing NewFault() method */
|
|
|
|
AB_Env_kFaultNullBreakString, /*i*/ /* 109 missing NewFault() method */
|
|
AB_Env_kFaultNullTraceString, /*i*/ /* 110 missing NewFault() method */
|
|
|
|
AB_Env_kFaultZeroErrno, /*i*/ /* 111 errno is unexpectedly zero */
|
|
|
|
AB_Env_kFaultBrokenEndian, /*i*/ /* 112 bad number in endianess code */
|
|
|
|
AB_Env_kFaultMethodStubOnly, /*i*/ /* 113 method not implemented */
|
|
AB_Env_kFaultWrongTag, /*i*/ /* 114 method not implemented */
|
|
AB_Env_kFaultNullSelfHandle, /*i*/ /* 115 method not implemented */
|
|
AB_Env_kFaultOutOfMemory, /*i*/ /* 116 failed memory allocation */
|
|
AB_Env_kFaultImportDuplicate, /*i*/ /* 117 duplicate entry imported */
|
|
AB_Env_kFaultOddImportPolicy /*i*/ /* 118 unknown import polity */
|
|
};
|
|
|
|
/* ----- ----- polymorphic dispatching virtual methods ----- ----- */
|
|
|
|
#define AB_Table_MakeEnv AB_OBSOLETE_METHOD
|
|
/*- MakeEnv creates a new AB_Env instances that must be destroyed later
|
|
with AB_Env_Free(), unless the caller feels like leaking the env, which
|
|
might be okay if very few are ever created.
|
|
|
|
The frontend will not need more than one environment, but making more
|
|
won't hurt. They are all interchangeable. Each env returns error status
|
|
after methods return. -*/
|
|
|
|
/* ----- ----- creation / ref counting ----- ----- */
|
|
|
|
AB_PUBLIC_API(AB_Env*) /* abenv.cpp */
|
|
AB_Env_New();
|
|
|
|
AB_PUBLIC_API(AB_Env*) /* abenv.cpp */
|
|
AB_Env_GetLogFileEnv(); /* do *not* release this (unless you first acquire) */
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abenv.cpp */
|
|
AB_Env_Acquire(AB_Env* self);
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abenv.cpp */
|
|
AB_Env_Release(AB_Env* self);
|
|
|
|
/* ----- ----- error access ----- ----- */
|
|
|
|
AB_PUBLIC_API(ab_error_count) /* abenv.cpp */
|
|
AB_Env_ForgetErrors(AB_Env* self);
|
|
/*- Discard all error information. -*/
|
|
|
|
AB_PUBLIC_API(ab_error_count) /* abenv.cpp */
|
|
AB_Env_ErrorCount(const AB_Env* self);
|
|
/*- Number of errors since last forget/reset. -*/
|
|
|
|
AB_PUBLIC_API(ab_error_uid) /* abenv.cpp */
|
|
AB_Env_GetError(const AB_Env* self);
|
|
/*- Last error since forget/reset, otherwise zero. -*/
|
|
|
|
AB_PUBLIC_API(ab_error_count) /* abenv.cpp */
|
|
AB_Env_GetAllErrors(const AB_Env* self,
|
|
ab_error_uid* outVector, ab_error_count inSize,
|
|
ab_error_count* outLength);
|
|
/*- All errors (up to inSize) since forget/reset. -*/
|
|
|
|
|
|
AB_PUBLIC_API(ab_error_uid) /* abenv.cpp */
|
|
AB_Env_NewFault(AB_Env* ev, ab_error_uid faultCode, ab_u4 faultSpace);
|
|
|
|
/* ----- ----- static dispatching methods ----- ----- */
|
|
|
|
AB_PUBLIC_API(ab_error_uid) /* abenv.cpp */
|
|
AB_Env_NewAbookFault(AB_Env* ev, ab_error_uid faultCode);
|
|
|
|
AB_PUBLIC_API(void) /* abenv.cpp */
|
|
AB_Env_Break(AB_Env* ev, const char* format, ...);
|
|
|
|
AB_PUBLIC_API(void) /* abenv.cpp */
|
|
AB_Env_Trace(AB_Env* ev, const char* format, ...);
|
|
|
|
AB_PUBLIC_API(void) /* abenv.cpp */
|
|
AB_Env_TraceBeginMethod(const AB_Env* ev, const char* cls, const char* method);
|
|
|
|
AB_PUBLIC_API(void) /* abenv.cpp */
|
|
AB_Env_TraceEndMethod(const AB_Env* ev);
|
|
|
|
|
|
/* ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ */
|
|
|
|
#if defined(AB_CONFIG_TRACE_CALL_TREE) && AB_CONFIG_TRACE_CALL_TREE
|
|
|
|
#define AB_Env_BeginMethod(ev,c,m) /*i*/ \
|
|
{ if ( (ev)->sEnv_DoTrace ) AB_Env_TraceBeginMethod((ev), (c), (m)); } {
|
|
|
|
#define AB_Env_EndMethod(ev) /*i*/ \
|
|
} { if ( (ev)->sEnv_DoTrace ) AB_Env_TraceEndMethod(ev); }
|
|
|
|
#else /* end AB_CONFIG_TRACE_CALL_TREE*/
|
|
|
|
#define AB_Env_BeginMethod(ev,c,m)
|
|
#define AB_Env_EndMethod(ev)
|
|
#endif /* end AB_CONFIG_TRACE_CALL_TREE*/
|
|
|
|
/* ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ ~~~~~ */
|
|
|
|
|
|
/* ----- ----- ----- ----- Async ----- ----- ----- ----- */
|
|
|
|
/*- We could arrange for AB_AsyncTask and AB_AsyncResult to be the
|
|
same object, but this causes interfaces that are less clear with respect to
|
|
cause an effect. -*/
|
|
|
|
#ifndef AB_AsyncTask_typedef
|
|
typedef struct AB_AsyncTask AB_AsyncTask;
|
|
#define AB_AsyncTask_typedef 1
|
|
#endif
|
|
|
|
/*- AB_AsyncTask is an abstract data type. You don't know its internal
|
|
structure. All that is known about this class is the methods that use this
|
|
type as an argument or return value.
|
|
|
|
AB_AsyncTask is a request to perform some operation asynchronously,
|
|
plus any information and callback hooks required to send progress
|
|
information and notifications to the task requestor. -*/
|
|
|
|
AB_PUBLIC_API(AB_AsyncResult*)
|
|
AB_AsyncTask_OpenTable(AB_AsyncTask* self, AB_Env* ev, DIR_Server* dir);
|
|
/*- OpenBook is an asynchronous version of AB_InitAddressBook(). -*/
|
|
|
|
#ifndef AB_AsyncResult_typedef
|
|
typedef struct AB_AsyncResult AB_AsyncResult;
|
|
#define AB_AsyncResult_typedef 1
|
|
#endif
|
|
/*- AB_AsyncResult is an abstract data type. You don't know its internal
|
|
structure. All that is known about this class is the methods that use this
|
|
type as an argument or return value.
|
|
|
|
AB_AsyncResult is a ticket (a task receipt) that allows a caller to
|
|
manipulate, examine, signal, etc. the asynchronous task assoociated
|
|
with an earlier task request (AB_AsyncTask). -*/
|
|
|
|
AB_PUBLIC_API(AB_Table*)
|
|
AB_AsyncResult_GetTable(AB_AsyncResult* self, AB_Env* ev);
|
|
/*- GetTable returns the table opened if ticket t was used in the call to
|
|
AB_Env_OpenTable(). This is a way of turning the OpenTable()
|
|
asynchronous call into a synchronous wait for the table to open. -*/
|
|
|
|
|
|
/* ----- ----- ----- ----- Tables ----- ----- ----- ----- */
|
|
|
|
|
|
#ifndef AB_Table_typedef
|
|
typedef struct AB_Table AB_Table;
|
|
#define AB_Table_typedef 1
|
|
#endif
|
|
/*3456789_123456789_123456789_123456789_123456789_123456789_123456789_12345678*/
|
|
|
|
typedef enum AB_Table_eError { /* AT_Table errors */
|
|
AB_Table_kFaultNullMethods = /*i*/ AB_Fault_kTable, /* 200 */
|
|
AB_Table_kFaultWrongMethodTag, /*i*/ /* 201 */
|
|
|
|
AB_Table_kFaultNullMakeEnv, /*i*/ /* 202 */
|
|
AB_Table_kFaultNullGetBookTable, /*i*/ /* 203 */
|
|
AB_Table_kFaultNullGetType, /*i*/ /* 204 */
|
|
AB_Table_kFaultNullGetTableRowUid, /*i*/ /* 205 */
|
|
AB_Table_kFaultNullGetRefCount, /*i*/ /* 206 */
|
|
|
|
AB_Table_kFaultNullAcquire, /*i*/ /* 207 */
|
|
AB_Table_kFaultNullRelease, /*i*/ /* 208 */
|
|
AB_Table_kFaultNullGetColumnName, /*i*/ /* 209 */
|
|
AB_Table_kFaultNullGetColumnId, /*i*/ /* 210 */
|
|
AB_Table_kFaultNullNewColumnId, /*i*/ /* 211 */
|
|
|
|
AB_Table_kFaultNullHasDisplayColumnProperty, /*i*/ /* 212 */
|
|
AB_Table_kFaultNullCountColumns, /*i*/ /* 213 */
|
|
AB_Table_kFaultNullGetColumnLayout, /*i*/ /* 214 */
|
|
AB_Table_kFaultNullGetDefaultLayout, /*i*/ /* 215 */
|
|
AB_Table_kFaultNullChangeColumnLayout, /*i*/ /* 216 */
|
|
|
|
AB_Table_kFaultNullGetColumnAt, /*i*/ /* 217 */
|
|
AB_Table_kFaultNullPutColumnAt, /*i*/ /* 218 */
|
|
AB_Table_kFaultNullAddColumnAt, /*i*/ /* 219 */
|
|
AB_Table_kFaultNullCutColumn, /*i*/ /* 220 */
|
|
AB_Table_kFaultNullCanSortByUid, /*i*/ /* 221 */
|
|
|
|
AB_Table_kFaultNullCanSortByName, /*i*/ /* 222 */
|
|
AB_Table_kFaultNullSortByUid, /*i*/ /* 223 */
|
|
AB_Table_kFaultNullSortByName, /*i*/ /* 224 */
|
|
AB_Table_kFaultNullGetSortColumn, /*i*/ /* 225 */
|
|
AB_Table_kFaultNullAcquireSortedTable, /*i*/ /* 226 */
|
|
|
|
AB_Table_kFaultNullAcquireSearchTable, /*i*/ /* 227 */
|
|
AB_Table_kFaultNullAddAllRows, /*i*/ /* 228 */
|
|
AB_Table_kFaultNullAddRow, /*i*/ /* 229 */
|
|
AB_Table_kFaultNullCutRow, /*i*/ /* 230 */
|
|
AB_Table_kFaultNullDestroyRow, /*i*/ /* 231 */
|
|
|
|
AB_Table_kFaultNullCountRows, /*i*/ /* 232 */
|
|
AB_Table_kFaultNullAcquireListsTable, /*i*/ /* 233 */
|
|
AB_Table_kFaultNullCountRowParents, /*i*/ /* 234 */
|
|
AB_Table_kFaultNullAcquireRowParentsTable, /*i*/ /* 235 */
|
|
AB_Table_kFaultNullCountRowChildren, /*i*/ /* 236 */
|
|
|
|
AB_Table_kFaultNullAcquireRowChildrenTable, /*i*/ /* 237 */
|
|
AB_Table_kFaultNullGetRowAt, /*i*/ /* 238 */
|
|
AB_Table_kFaultNullGetRows, /*i*/ /* 239 */
|
|
AB_Table_kFaultNullDoesSortRows, /*i*/ /* 240 */
|
|
AB_Table_kFaultNullRowPos, /*i*/ /* 241 */
|
|
|
|
AB_Table_kFaultNullChangeRowPos, /*i*/ /* 242 */
|
|
AB_Table_kFaultNullCountRowCells, /*i*/ /* 243 */
|
|
AB_Table_kFaultNullMakeDefaultRow, /*i*/ /* 244 */
|
|
AB_Table_kFaultNullMakeRow, /*i*/ /* 245 */
|
|
AB_Table_kFaultNullMakeRowFromColumns, /*i*/ /* 246 */
|
|
|
|
AB_Table_kFaultNullGetPersonCells, /*i*/ /* 247 */
|
|
AB_Table_kFaultNullGetListCells, /*i*/ /* 248 */
|
|
AB_Table_kFaultNullCutRowRange, /*i*/ /* 249 */
|
|
|
|
AB_Table_kFaultNullNewRowAt, /*i*/ /* 250 */
|
|
AB_Table_kFaultNullReadRowAt, /*i*/ /* 251 */
|
|
AB_Table_kFaultNullReadRow, /*i*/ /* 252 */
|
|
AB_Table_kFaultNullReadAllRowCells, /*i*/ /* 253 */
|
|
AB_Table_kFaultNullUpdateRow, /*i*/ /* 254 */
|
|
AB_Table_kFaultNullResetRow, /*i*/ /* 255 */
|
|
|
|
AB_Table_kFaultWrongBodyTag, /*i*/ /* 256 */
|
|
AB_Table_kFaultMiscTagTypeFailure, /*i*/ /* 257 */
|
|
AB_Table_kFaultWrongTag, /*i*/ /* 258 */
|
|
AB_Table_kFaultOutOfMemory, /*i*/ /* 259 */
|
|
AB_Table_kFaultMissingDeadTag, /*i*/ /* 260 */
|
|
|
|
AB_Table_kFaultBodyNotAvailable, /*i*/ /* 261 */
|
|
AB_Table_kFaultMissingContainerTable, /*i*/ /* 262 */
|
|
AB_Table_kFaultRowsNotSortable, /*i*/ /* 263 */
|
|
AB_Table_kFaultRowsNotSearchable, /*i*/ /* 264 */
|
|
|
|
AB_Table_kFaultNullDefaultsSlot, /*i*/ /* 265 */
|
|
AB_Table_kFaultNullNameSetSlot, /*i*/ /* 266 */
|
|
AB_Table_kFaultNullColumnSetSlot, /*i*/ /* 267 */
|
|
AB_Table_kFaultNullRowSetSlot, /*i*/ /* 268 */
|
|
AB_Table_kFaultNullRowContentSlot, /*i*/ /* 269 */
|
|
|
|
AB_Table_kFaultNotOpenTable, /*i*/ /* 270 */
|
|
AB_Table_kFaultUnknownStaticFail, /*i*/ /* 271 */
|
|
AB_Table_kFaultNullViewSlot /*i*/ /* 272 */
|
|
} AB_Table_eError;
|
|
|
|
/*#define AB_Table_kFaultNull Foo (AB_Fault_kTable + x)*/
|
|
|
|
|
|
/*- AB_Table is an abstract data type. You don't know its internal structure.
|
|
All that is known about this class is the methods that use this type as an
|
|
argument or return value. -*/
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abtable.cpp */
|
|
AB_GetGlobalTable();
|
|
/*- GetGlobalTable returns a global table manager. All address book
|
|
content is part of this table. If there are multiple personal address books,
|
|
then each of these address books appears as one row inside this uber
|
|
table. Among other things, this interface unifies the appearance of per
|
|
address book properties, because address book properties are just values
|
|
appearing in the cells of columns for each.
|
|
|
|
(This global table can have a row describing itself, but this might be
|
|
sick.)
|
|
|
|
We could put LDAP directories into this table to unify directories and
|
|
address books. At least this would allow directories to be described by
|
|
propertries appearing in columns for each directory row. -*/
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abtable.cpp */
|
|
AB_Table_GetBookTable(const AB_Table* self, AB_Env* ev);
|
|
/*- GetBookTable returns the address book table containing this table. If
|
|
self is itself the address book then self is returned. -*/
|
|
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
typedef enum AB_Table_eType /*d*/ {
|
|
AB_Table_kNone = 0, /* row is not a table */
|
|
AB_Table_kGlobal = 1, /* see AB_GetGlobalTable() */
|
|
AB_Table_kAddressBook = 2, /* personal address book */
|
|
AB_Table_kDirectory = 3, /* LDAP directory */
|
|
AB_Table_kMailingList = 4, /* a mailing list entry */
|
|
AB_Table_kParentList = 5, /* all tables containing a table or row */
|
|
AB_Table_kListSubset = 6, /* row subset of lists only */
|
|
AB_Table_kSearchResult = 7, /* typedown or other search result */
|
|
|
|
AB_Table_kNumberOfTypes = 8 /* must be last of enums */
|
|
|
|
} AB_Table_eType;
|
|
|
|
AB_PUBLIC_API(AB_Table_eType) /* abtable.cpp */
|
|
AB_Table_GetType(AB_Table* self, AB_Env* ev);
|
|
/*- IsBookTable returns whether table t is an address book. -*/
|
|
|
|
|
|
AB_PUBLIC_API(ab_row_uid) /* abtable.cpp */
|
|
AB_Table_GetTableRowUid(AB_Table* self, AB_Env* ev);
|
|
/*- GetTableRowUid returns the row uid for table self. If self is a global
|
|
table (AB_Type_kGlobalTable, AB_GetGlobalTable()), then all such
|
|
global uid's are globally unique. If self is a list inside a p -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abtable.cpp */
|
|
AB_Table_GetRefCount(const AB_Table* self, AB_Env* ev);
|
|
/*- GetRefCount returns the current number of references to this table
|
|
instance in the current runtime session. This reference count is not
|
|
persistent. It only reflects the number of times that a table has been
|
|
acquired and not released. When a table is released enough times that it's
|
|
ref count becomes zero, then the table is deallocated.
|
|
|
|
Frontends might not need to deal with table reference counts. The
|
|
interface will try to be set up so this issue can be ignored as long as all
|
|
usage rules are followed. -*/
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abtable.cpp */
|
|
AB_Table_Acquire(AB_Table* self, AB_Env* ev);
|
|
/*- Acquire increments the table's refcount. Perhaps frontends will never
|
|
need to do this. For example, this occurs automatically when a frontend
|
|
allocates a row by calling AB_Table_MakeRow(); -*/
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abtable.cpp */
|
|
AB_Table_Release(AB_Table* self, AB_Env* ev);
|
|
/*- Release decrements the table's refcount. Perhaps frontends will never
|
|
need to do this. For example, this occurs automatically when a frontend
|
|
deallocates a row by calling AB_Row_Free(); -*/
|
|
|
|
AB_PUBLIC_API(void) /* abtable.cpp */
|
|
AB_Table_Close(AB_Table* self, AB_Env* ev);
|
|
/*- Close closes the table. -*/
|
|
|
|
|
|
/* ----- ----- ----- ----- Columns ----- ----- ----- ----- */
|
|
|
|
|
|
/*- (The notion of column replaces the old notion of token. A token
|
|
means something more general, but the previously described address
|
|
book model was only using tokens to descibe attribute names in
|
|
schemas, and in the table model these are just names of columns.) -*/
|
|
|
|
AB_PUBLIC_API(const char*) /* abtable.cpp */
|
|
AB_Table_GetColumnName(AB_Table* self, AB_Env* ev, ab_column_uid col);
|
|
/*- GetColumnName returns a constant string (do not modify or delete)
|
|
which is the string representation of col. A null pointer is returned if
|
|
this table does not know this given column uid.
|
|
|
|
The self table need not be the address book, but if not the address book
|
|
table will be looked up (with AB_Table_GetBookTable()) and this table
|
|
will be used instead. -*/
|
|
|
|
AB_PUBLIC_API(ab_column_uid) /* abtable.cpp */
|
|
AB_Table_GetColumnId(const AB_Table* self, AB_Env* ev, const char* name);
|
|
/*- GetColumnId returns the column id associated. A zero uid is returned if
|
|
this table does not know the given column name. This method must be
|
|
used instead of NewColumnId when the address book is readonly and
|
|
cannot be modified.
|
|
|
|
The self table need not be the address book, but if not the address book
|
|
table will be looked up (with AB_Table_GetBookTable()) and this table
|
|
will be used instead. -*/
|
|
|
|
AB_PUBLIC_API(ab_column_uid) /* abtable.cpp */
|
|
AB_Table_NewColumnId(AB_Table* self, AB_Env* ev, const char* name);
|
|
/*- NewColumnId is like GetColumnId except that if name is not
|
|
already known as a column in the address book, this method will modify
|
|
the address book and its table so that in the future name is known by
|
|
the persisent column uid returned. So a zero uid will not be returned
|
|
unless an error occurs.
|
|
|
|
The self table need not be the address book, but if not the address book
|
|
table will be looked up (with AB_Table_GetBookTable()) and this table
|
|
will be used instead. -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_HasDisplayColumnProperty(const AB_Table* self, AB_Env* ev);
|
|
/*- HasDisplayColumnProperty returns whether this table has its own
|
|
specialized property that configures which columns it will display. If
|
|
not, this table will default to using the columns for the containing
|
|
address book. This method allows inspection of whether this table has
|
|
overriden the address book defaults that will otherwise be used by the
|
|
various column methods defined on AB_Table. -*/
|
|
|
|
AB_PUBLIC_API(ab_column_count) /* abtable.cpp */
|
|
AB_Table_CountColumns(const AB_Table* self, AB_Env* ev);
|
|
/*- CountColumns returns the number of display columns for this table.
|
|
This is just a subset of information returned by GetColumns. -*/
|
|
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
#ifndef AB_Column_typedef
|
|
typedef struct AB_Column AB_Column;
|
|
#define AB_Column_typedef 1
|
|
#endif
|
|
|
|
struct AB_Column {
|
|
const char* sColumn_Name; /* the "real" name of this column */
|
|
const char* sColumn_DisplayName; /* display name for column if non-null */
|
|
ab_column_uid sColumn_Uid; /* the uid for sColumn_Name if nonzero */
|
|
ab_column_uid sColumn_SecondSort; /* if non-zero, secondary sort attribute */
|
|
ab_cell_size sColumn_CellSize; /* size of row cells for this column */
|
|
ab_bool sColumn_CanSort; /* the table can sort by this column */
|
|
};
|
|
|
|
enum {
|
|
AB_Column_kFaultNotStandardName = /*i*/ AB_Fault_kColumn, /* 400 */
|
|
AB_Column_kFaultNotStandardUid, /*i*/ /* 401 */
|
|
AB_Column_kFaultNotColumnUid, /*i*/ /* 402 */
|
|
AB_Column_kFaultSortNotSupported, /*i*/ /* 403 */
|
|
AB_Column_kFaultColumnUidTooLarge /*i*/ /* 404 */
|
|
};
|
|
|
|
|
|
/* You *cannot* change following enum names or values. So comments containing
|
|
** the numbers will never need different numbers, so you'll never experience
|
|
** the tedium of changing the comment numbers. The enum names and column
|
|
** name strings should have exactly the same (case independent) letters.
|
|
**
|
|
** So if you feel compelled to change column names, by all means do so, but
|
|
** add a new enum with the new column name, and *do not change existing enums*
|
|
** either by name or numerical value. Just stop using old standard columns
|
|
** if you don't want to use them.
|
|
**
|
|
** Don't even bother changing the white space that groups names five at a
|
|
** time, since grouping no longer matters as much as not moving names. This
|
|
** enum represents a pre-tokenized standard name table, and the names and
|
|
** tokens cannot be changed without breaking the table.
|
|
*/
|
|
|
|
typedef enum {
|
|
AB_Attrib_kIsPerson = 0, /* 00 - "isperson" (t or f) */
|
|
AB_Attrib_kModTime, /* 01 - "modtime" */
|
|
AB_Attrib_kFullName, /* 02 - "fullname" */
|
|
AB_Attrib_kNickname, /* 03 - "nickname" */
|
|
AB_Attrib_kMiddleName, /* 04 - "middlename" */
|
|
|
|
AB_Attrib_kFamilyName, /* 05 - "familyname" */
|
|
AB_Attrib_kCompanyName, /* 06 - "companyname" */
|
|
AB_Attrib_kRegion, /* 07 - "region" */
|
|
AB_Attrib_kEmail, /* 08 - "email" */
|
|
AB_Attrib_kInfo, /* 09 - "info" */
|
|
|
|
AB_Attrib_kHtmlMail, /* 10 - "htmlmail" (t or f) */
|
|
AB_Attrib_kExpandedName, /* 11 - "expandedname" */
|
|
AB_Attrib_kTitle, /* 12 - "title" */
|
|
AB_Attrib_kAddress, /* 13 - "address" */
|
|
AB_Attrib_kZip, /* 14 - "zip" */
|
|
|
|
AB_Attrib_kCountry, /* 15 - "country" */
|
|
AB_Attrib_kWorkPhone, /* 16 - "workphone" */
|
|
AB_Attrib_kHomePhone, /* 17 - "homephone" */
|
|
AB_Attrib_kSecurity, /* 18 - "security" */
|
|
AB_Attrib_kCoolAddress, /* 19 - "cooladdress" (conference related) */
|
|
|
|
AB_Attrib_kUseServer, /* 20 - "useserver" (conference related) */
|
|
AB_Attrib_kPager, /* 21 - "pager" */
|
|
AB_Attrib_kFax, /* 22 - "fax" */
|
|
AB_Attrib_kDisplayName, /* 23 - "displayname" */
|
|
AB_Attrib_kSender, /* 24 - "sender" (mail and news) */
|
|
|
|
AB_Attrib_kSubject, /* 25 - "subject" */
|
|
AB_Attrib_kBody, /* 26 - "body" */
|
|
AB_Attrib_kDate, /* 27 - "date" */
|
|
AB_Attrib_kPriority, /* 28 - "priority" (mail only) */
|
|
AB_Attrib_kMsgStatus, /* 29 - "msgstatus" */
|
|
|
|
AB_Attrib_kTo, /* 30 - "to" */
|
|
AB_Attrib_kCC, /* 31 - "cc" */
|
|
AB_Attrib_kToOrCC, /* 32 - "toorcc" */
|
|
AB_Attrib_kCommonName, /* 33 - "commonname" (LDAP only) */
|
|
AB_Attrib_k822Address, /* 34 - "822address" */
|
|
|
|
AB_Attrib_kPhoneNumber, /* 35 - "phonenumber" */
|
|
AB_Attrib_kOrganization, /* 36 - "organization" */
|
|
AB_Attrib_kOrgUnit, /* 37 - "orgunit" */
|
|
AB_Attrib_kLocality, /* 38 - "locality" */
|
|
AB_Attrib_kStreetAddress, /* 39 - "streetaddress" */
|
|
|
|
AB_Attrib_kSize, /* 40 - "size" */
|
|
AB_Attrib_kAnyText, /* 41 - "anytext" (any header or body) */
|
|
AB_Attrib_kKeywords, /* 42 - "keywords" */
|
|
AB_Attrib_kDistName, /* 43 - "distname" (distinguished name) */
|
|
AB_Attrib_kObjectClass, /* 44 - "objectclass" */
|
|
|
|
AB_Attrib_kJpegFile, /* 45 - "jpegfile" */
|
|
AB_Attrib_kLocation, /* 46 - "location" (result list only */
|
|
AB_Attrib_kMessageKey, /* 47 - "messagekey" (message result elems) */
|
|
AB_Attrib_kAgeInDays, /* 48 - "ageindays" (purging old news) */
|
|
AB_Attrib_kGivenName, /* 49 - "givenname" (sorting LDAP results) */
|
|
|
|
AB_Attrib_kSurname, /* 50 - "surname" */
|
|
AB_Attrib_kFolderInfo, /* 51 - "folderinfo" (view thread context) */
|
|
AB_Attrib_kCustom1, /* 52 - "custom1" (custom LDAP attribs) */
|
|
AB_Attrib_kCustom2, /* 53 - "custom2" */
|
|
AB_Attrib_kCustom3, /* 54 - "custom3" */
|
|
|
|
AB_Attrib_kCustom4, /* 55 - "custom4" */
|
|
AB_Attrib_kCustom5, /* 56 - "custom5" */
|
|
AB_Attrib_kMessageId, /* 57 - "messageid" */
|
|
AB_Attrib_kHomeUrl, /* 58 - "homeurl" */
|
|
AB_Attrib_kWorkUrl, /* 59 - "workurl" */
|
|
|
|
AB_Attrib_kImapUrl, /* 60 - "imapurl" */
|
|
AB_Attrib_kNotifyUrl, /* 61 - "notifyurl" */
|
|
AB_Attrib_kPrefUrl, /* 62 - "prefurl" */
|
|
AB_Attrib_kPagerEmail, /* 63 - "pageremail" */
|
|
AB_Attrib_kParentPhone, /* 64 - "parentphone" */
|
|
|
|
AB_Attrib_kGender, /* 65 - "gender" */
|
|
AB_Attrib_kPostalAddress, /* 66 - "postaladdress" */
|
|
AB_Attrib_kEmployeeId, /* 67 - "employeeid" */
|
|
AB_Attrib_kAgent, /* 68 - "agent" */
|
|
AB_Attrib_kBbs, /* 69 - "bbs" */
|
|
|
|
AB_Attrib_kBday, /* 70 - "bday" (birthdate) */
|
|
AB_Attrib_kCalendar, /* 71 - "calendar" */
|
|
AB_Attrib_kCar, /* 72 - "car" */
|
|
AB_Attrib_kCarPhone, /* 73 - "carphone" */
|
|
AB_Attrib_kCategories, /* 74 - "categories" */
|
|
|
|
AB_Attrib_kCell, /* 75 - "cell" */
|
|
AB_Attrib_kCellPhone, /* 76 - "cellphone" */
|
|
AB_Attrib_kCharSet, /* 77 - "charset" (cs, csid) */
|
|
AB_Attrib_kClass, /* 78 - "class" */
|
|
AB_Attrib_kGeo, /* 79 - "geo" */
|
|
|
|
AB_Attrib_kGif, /* 80 - "gif" */
|
|
AB_Attrib_kKey, /* 81 - "key" (publickey) */
|
|
AB_Attrib_kLanguage, /* 82 - "language" */
|
|
AB_Attrib_kLogo, /* 83 - "logo" */
|
|
AB_Attrib_kModem, /* 84 - "modem" */
|
|
|
|
AB_Attrib_kMsgPhone, /* 85 - "msgphone" */
|
|
AB_Attrib_kN, /* 86 - "n" */
|
|
AB_Attrib_kNote, /* 87 - "note" */
|
|
AB_Attrib_kPagerPhone, /* 88 - "pagerphone" */
|
|
AB_Attrib_kPgp, /* 89 - "pgp" */
|
|
|
|
AB_Attrib_kPhoto, /* 90 - "photo" */
|
|
AB_Attrib_kRev, /* 91 - "rev" */
|
|
AB_Attrib_kRole, /* 92 - "role" */
|
|
AB_Attrib_kSound, /* 93 - "sound" */
|
|
AB_Attrib_kSortString, /* 94 - "sortstring" */
|
|
|
|
AB_Attrib_kTiff, /* 95 - "tiff" */
|
|
AB_Attrib_kTz, /* 96 - "tz" (timezone) */
|
|
AB_Attrib_kUid, /* 97 - "uid" (uniqueid) */
|
|
AB_Attrib_kVersion, /* 98 - "version" */
|
|
AB_Attrib_kVoice, /* 99 - "voice" */
|
|
|
|
AB_Attrib_kNumColumnAttributes /* 100 - must be last enum value listed */
|
|
|
|
} AB_Column_eAttribute;
|
|
|
|
/*3456789_123456789_123456789_123456789_123456789_123456789_123456789_12345678*/
|
|
|
|
|
|
typedef enum AB_Column_eDefaultSizes { /* defaults for new row cell sizes */
|
|
AB_Column_kSize_IsPerson = 4,
|
|
AB_Column_kSize_ModTime = 18,
|
|
AB_Column_kSize_FullName = 256,
|
|
AB_Column_kSize_Nickname = 64,
|
|
|
|
AB_Column_kSize_MiddleName = 64,
|
|
AB_Column_kSize_FamilyName = 64,
|
|
AB_Column_kSize_CompanyName = 128,
|
|
AB_Column_kSize_Region = 128,
|
|
AB_Column_kSize_Email = 256,
|
|
AB_Column_kSize_Info = 1024,
|
|
AB_Column_kSize_HtmlMail = 8,
|
|
AB_Column_kSize_ExpandedName = 256,
|
|
AB_Column_kSize_Title = 64,
|
|
AB_Column_kSize_Address = 256,
|
|
AB_Column_kSize_Zip = 48,
|
|
|
|
AB_Column_kSize_Country = 48,
|
|
AB_Column_kSize_WorkPhone = 48,
|
|
AB_Column_kSize_HomePhone = 48,
|
|
AB_Column_kSize_Security = 16,
|
|
AB_Column_kSize_CoolAddress = 256,
|
|
AB_Column_kSize_UseServer = 16,
|
|
AB_Column_kSize_Pager = 48,
|
|
AB_Column_kSize_Fax = 48,
|
|
AB_Column_kSize_DisplayName = 64,
|
|
|
|
AB_Column_kSize_Sender = 128,
|
|
AB_Column_kSize_Subject = 256,
|
|
AB_Column_kSize_Body = 1024,
|
|
AB_Column_kSize_Date = 64,
|
|
|
|
AB_Column_kSize_Priority = 32,
|
|
AB_Column_kSize_MsgStatus = 32,
|
|
AB_Column_kSize_To = 256,
|
|
AB_Column_kSize_CC = 256,
|
|
AB_Column_kSize_ToOrCC = 256,
|
|
|
|
AB_Column_kSize_CommonName = 256,
|
|
AB_Column_kSize_822Address = 256,
|
|
AB_Column_kSize_PhoneNumber = 64,
|
|
AB_Column_kSize_Organization = 128,
|
|
AB_Column_kSize_OrgUnit = 64,
|
|
AB_Column_kSize_Locality = 128,
|
|
AB_Column_kSize_StreetAddress = 256,
|
|
AB_Column_kSize_Size = 32,
|
|
AB_Column_kSize_AnyText = 256,
|
|
AB_Column_kSize_Keywords = 256,
|
|
|
|
AB_Column_kMaxSize_DistName = (32 * 1024),
|
|
AB_Column_kSize_DistName = 512,
|
|
AB_Column_kSize_ObjectClass = 32,
|
|
AB_Column_kSize_JpegFile = 1024,
|
|
|
|
AB_Column_kSize_Location = 64,
|
|
AB_Column_kSize_MessageKey = 32,
|
|
|
|
AB_Column_kSize_AgeInDays = 16,
|
|
|
|
AB_Column_kSize_GivenName = 64,
|
|
AB_Column_kSize_Surname = 64,
|
|
|
|
AB_Column_kSize_FolderInfo = 256,
|
|
|
|
AB_Column_kSize_Custom1 = 64,
|
|
AB_Column_kSize_Custom2 = 64,
|
|
AB_Column_kSize_Custom3 = 64,
|
|
AB_Column_kSize_Custom4 = 64,
|
|
AB_Column_kSize_Custom5 = 64,
|
|
|
|
AB_Column_kSize_MessageId = 32,
|
|
|
|
AB_Column_kSize_HomeUrl = 128,
|
|
AB_Column_kSize_WorkUrl = 128,
|
|
AB_Column_kSize_ImapUrl = 128,
|
|
AB_Column_kSize_NotifyUrl = 128,
|
|
AB_Column_kSize_PrefUrl = 128,
|
|
AB_Column_kSize_PagerEmail = 48,
|
|
|
|
AB_Column_kSize_ParentPhone = 48,
|
|
AB_Column_kSize_Gender = 16,
|
|
AB_Column_kSize_PostalAddress = 128,
|
|
|
|
AB_Column_kSize_EmployeeId = 32,
|
|
|
|
AB_Column_kSize_Agent = 128,
|
|
AB_Column_kSize_Bbs = 48,
|
|
AB_Column_kSize_Bday = 32,
|
|
AB_Column_kSize_Calendar = 256,
|
|
AB_Column_kSize_Car = 48,
|
|
AB_Column_kSize_CarPhone = 48,
|
|
AB_Column_kSize_Categories = 64,
|
|
AB_Column_kSize_Cell = 48,
|
|
AB_Column_kSize_CellPhone = 48,
|
|
AB_Column_kSize_CharSet = 16,
|
|
AB_Column_kSize_Class = 64,
|
|
AB_Column_kSize_Geo = 256,
|
|
AB_Column_kSize_Gif = 1024,
|
|
AB_Column_kSize_Key = 256,
|
|
AB_Column_kSize_Language = 64,
|
|
AB_Column_kSize_Logo = 1024,
|
|
AB_Column_kSize_Modem = 48,
|
|
AB_Column_kSize_MsgPhone = 48,
|
|
AB_Column_kSize_N = 256,
|
|
AB_Column_kSize_Note = 512,
|
|
AB_Column_kSize_PagerPhone = 48,
|
|
AB_Column_kSize_Pgp = 512,
|
|
AB_Column_kSize_Photo = 1024,
|
|
AB_Column_kSize_Rev = 128,
|
|
AB_Column_kSize_Role = 64,
|
|
AB_Column_kSize_Sound = 1024,
|
|
AB_Column_kSize_SortString = 64,
|
|
AB_Column_kSize_Tiff = 1024,
|
|
AB_Column_kSize_Tz = 64,
|
|
AB_Column_kSize_Uid = 128,
|
|
AB_Column_kSize_Version = 64,
|
|
AB_Column_kSize_Voice = 48
|
|
} AB_Column_eDefaultSizes;
|
|
|
|
typedef enum AB_Column_eUid {
|
|
AB_Column_kIsPerson = AB_Attrib_AsStdColUid(AB_Attrib_kIsPerson),
|
|
AB_Column_kModTime = AB_Attrib_AsStdColUid(AB_Attrib_kModTime),
|
|
AB_Column_kFullName = AB_Attrib_AsStdColUid(AB_Attrib_kFullName),
|
|
AB_Column_kNickname = AB_Attrib_AsStdColUid(AB_Attrib_kNickname),
|
|
|
|
AB_Column_kMiddleName = AB_Attrib_AsStdColUid(AB_Attrib_kMiddleName),
|
|
AB_Column_kFamilyName = AB_Attrib_AsStdColUid(AB_Attrib_kFamilyName),
|
|
AB_Column_kCompanyName = AB_Attrib_AsStdColUid(AB_Attrib_kCompanyName),
|
|
AB_Column_kRegion = AB_Attrib_AsStdColUid(AB_Attrib_kRegion),
|
|
AB_Column_kEmail = AB_Attrib_AsStdColUid(AB_Attrib_kEmail),
|
|
AB_Column_kInfo = AB_Attrib_AsStdColUid(AB_Attrib_kInfo),
|
|
AB_Column_kHtmlMail = AB_Attrib_AsStdColUid(AB_Attrib_kHtmlMail),
|
|
AB_Column_kExpandedName = AB_Attrib_AsStdColUid(AB_Attrib_kExpandedName),
|
|
AB_Column_kTitle = AB_Attrib_AsStdColUid(AB_Attrib_kTitle),
|
|
AB_Column_kAddress = AB_Attrib_AsStdColUid(AB_Attrib_kAddress),
|
|
AB_Column_kZip = AB_Attrib_AsStdColUid(AB_Attrib_kZip),
|
|
|
|
AB_Column_kCountry = AB_Attrib_AsStdColUid(AB_Attrib_kCountry),
|
|
AB_Column_kWorkPhone = AB_Attrib_AsStdColUid(AB_Attrib_kWorkPhone),
|
|
AB_Column_kHomePhone = AB_Attrib_AsStdColUid(AB_Attrib_kHomePhone),
|
|
AB_Column_kSecurity = AB_Attrib_AsStdColUid(AB_Attrib_kSecurity),
|
|
AB_Column_kCoolAddress = AB_Attrib_AsStdColUid(AB_Attrib_kCoolAddress),
|
|
AB_Column_kUseServer = AB_Attrib_AsStdColUid(AB_Attrib_kUseServer),
|
|
AB_Column_kPager = AB_Attrib_AsStdColUid(AB_Attrib_kPager),
|
|
AB_Column_kFax = AB_Attrib_AsStdColUid(AB_Attrib_kFax),
|
|
AB_Column_kDisplayName = AB_Attrib_AsStdColUid(AB_Attrib_kDisplayName),
|
|
|
|
AB_Column_kSender = AB_Attrib_AsStdColUid(AB_Attrib_kSender),
|
|
AB_Column_kSubject = AB_Attrib_AsStdColUid(AB_Attrib_kSubject),
|
|
AB_Column_kBody = AB_Attrib_AsStdColUid(AB_Attrib_kBody),
|
|
AB_Column_kDate = AB_Attrib_AsStdColUid(AB_Attrib_kDate),
|
|
|
|
AB_Column_kPriority = AB_Attrib_AsStdColUid(AB_Attrib_kPriority),
|
|
AB_Column_kMsgStatus = AB_Attrib_AsStdColUid(AB_Attrib_kMsgStatus),
|
|
AB_Column_kTo = AB_Attrib_AsStdColUid(AB_Attrib_kTo),
|
|
AB_Column_kCC = AB_Attrib_AsStdColUid(AB_Attrib_kCC),
|
|
AB_Column_kToOrCC = AB_Attrib_AsStdColUid(AB_Attrib_kToOrCC),
|
|
|
|
AB_Column_kCommonName = AB_Attrib_AsStdColUid(AB_Attrib_kCommonName),
|
|
AB_Column_k822Address = AB_Attrib_AsStdColUid(AB_Attrib_k822Address),
|
|
AB_Column_kPhoneNumber = AB_Attrib_AsStdColUid(AB_Attrib_kPhoneNumber),
|
|
AB_Column_kOrganization = AB_Attrib_AsStdColUid(AB_Attrib_kOrganization),
|
|
AB_Column_kOrgUnit = AB_Attrib_AsStdColUid(AB_Attrib_kOrgUnit),
|
|
AB_Column_kLocality = AB_Attrib_AsStdColUid(AB_Attrib_kLocality),
|
|
AB_Column_kStreetAddress = AB_Attrib_AsStdColUid(AB_Attrib_kStreetAddress),
|
|
AB_Column_kSize = AB_Attrib_AsStdColUid(AB_Attrib_kSize),
|
|
AB_Column_kAnyText = AB_Attrib_AsStdColUid(AB_Attrib_kAnyText),
|
|
AB_Column_kKeywords = AB_Attrib_AsStdColUid(AB_Attrib_kKeywords),
|
|
|
|
AB_Column_kDistName = AB_Attrib_AsStdColUid(AB_Attrib_kDistName),
|
|
AB_Column_kObjectClass = AB_Attrib_AsStdColUid(AB_Attrib_kObjectClass),
|
|
AB_Column_kJpegFile = AB_Attrib_AsStdColUid(AB_Attrib_kJpegFile),
|
|
|
|
AB_Column_kLocation = AB_Attrib_AsStdColUid(AB_Attrib_kLocation),
|
|
AB_Column_kMessageKey = AB_Attrib_AsStdColUid(AB_Attrib_kMessageKey),
|
|
|
|
AB_Column_kAgeInDays = AB_Attrib_AsStdColUid(AB_Attrib_kAgeInDays),
|
|
|
|
AB_Column_kGivenName = AB_Attrib_AsStdColUid(AB_Attrib_kGivenName),
|
|
AB_Column_kSurname = AB_Attrib_AsStdColUid(AB_Attrib_kSurname),
|
|
|
|
AB_Column_kFolderInfo = AB_Attrib_AsStdColUid(AB_Attrib_kFolderInfo),
|
|
|
|
AB_Column_kCustom1 = AB_Attrib_AsStdColUid(AB_Attrib_kCustom1),
|
|
AB_Column_kCustom2 = AB_Attrib_AsStdColUid(AB_Attrib_kCustom2),
|
|
AB_Column_kCustom3 = AB_Attrib_AsStdColUid(AB_Attrib_kCustom3),
|
|
AB_Column_kCustom4 = AB_Attrib_AsStdColUid(AB_Attrib_kCustom4),
|
|
AB_Column_kCustom5 = AB_Attrib_AsStdColUid(AB_Attrib_kCustom5),
|
|
|
|
AB_Column_kMessageId = AB_Attrib_AsStdColUid(AB_Attrib_kMessageId),
|
|
|
|
AB_Column_kHomeUrl = AB_Attrib_AsStdColUid(AB_Attrib_kHomeUrl),
|
|
AB_Column_kWorkUrl = AB_Attrib_AsStdColUid(AB_Attrib_kWorkUrl),
|
|
AB_Column_kImapUrl = AB_Attrib_AsStdColUid(AB_Attrib_kImapUrl),
|
|
AB_Column_kNotifyUrl = AB_Attrib_AsStdColUid(AB_Attrib_kNotifyUrl),
|
|
AB_Column_kPrefUrl = AB_Attrib_AsStdColUid(AB_Attrib_kPrefUrl),
|
|
AB_Column_kPagerEmail = AB_Attrib_AsStdColUid(AB_Attrib_kPagerEmail),
|
|
|
|
AB_Column_kParentPhone = AB_Attrib_AsStdColUid(AB_Attrib_kParentPhone),
|
|
AB_Column_kGender = AB_Attrib_AsStdColUid(AB_Attrib_kGender),
|
|
AB_Column_kPostalAddress = AB_Attrib_AsStdColUid(AB_Attrib_kPostalAddress),
|
|
|
|
AB_Column_kEmployeeId = AB_Attrib_AsStdColUid(AB_Attrib_kEmployeeId),
|
|
|
|
AB_Column_kAgent = AB_Attrib_AsStdColUid(AB_Attrib_kAgent),
|
|
AB_Column_kBbs = AB_Attrib_AsStdColUid(AB_Attrib_kBbs),
|
|
AB_Column_kBday = AB_Attrib_AsStdColUid(AB_Attrib_kBday),
|
|
AB_Column_kCalendar = AB_Attrib_AsStdColUid(AB_Attrib_kCalendar),
|
|
AB_Column_kCar = AB_Attrib_AsStdColUid(AB_Attrib_kCar),
|
|
AB_Column_kCarPhone = AB_Attrib_AsStdColUid(AB_Attrib_kCarPhone),
|
|
AB_Column_kCategories = AB_Attrib_AsStdColUid(AB_Attrib_kCategories),
|
|
AB_Column_kCell = AB_Attrib_AsStdColUid(AB_Attrib_kCell),
|
|
AB_Column_kCellPhone = AB_Attrib_AsStdColUid(AB_Attrib_kCellPhone),
|
|
AB_Column_kCharSet = AB_Attrib_AsStdColUid(AB_Attrib_kCharSet),
|
|
AB_Column_kClass = AB_Attrib_AsStdColUid(AB_Attrib_kClass),
|
|
AB_Column_kGeo = AB_Attrib_AsStdColUid(AB_Attrib_kGeo),
|
|
AB_Column_kGif = AB_Attrib_AsStdColUid(AB_Attrib_kGif),
|
|
AB_Column_kKey = AB_Attrib_AsStdColUid(AB_Attrib_kKey),
|
|
AB_Column_kLanguage = AB_Attrib_AsStdColUid(AB_Attrib_kLanguage),
|
|
AB_Column_kLogo = AB_Attrib_AsStdColUid(AB_Attrib_kLogo),
|
|
AB_Column_kModem = AB_Attrib_AsStdColUid(AB_Attrib_kModem),
|
|
AB_Column_kMsgPhone = AB_Attrib_AsStdColUid(AB_Attrib_kMsgPhone),
|
|
AB_Column_kN = AB_Attrib_AsStdColUid(AB_Attrib_kN),
|
|
AB_Column_kNote = AB_Attrib_AsStdColUid(AB_Attrib_kNote),
|
|
AB_Column_kPagerPhone = AB_Attrib_AsStdColUid(AB_Attrib_kPagerPhone),
|
|
AB_Column_kPgp = AB_Attrib_AsStdColUid(AB_Attrib_kPgp),
|
|
AB_Column_kPhoto = AB_Attrib_AsStdColUid(AB_Attrib_kPhoto),
|
|
AB_Column_kRev = AB_Attrib_AsStdColUid(AB_Attrib_kRev),
|
|
AB_Column_kRole = AB_Attrib_AsStdColUid(AB_Attrib_kRole),
|
|
AB_Column_kSound = AB_Attrib_AsStdColUid(AB_Attrib_kSound),
|
|
AB_Column_kSortString = AB_Attrib_AsStdColUid(AB_Attrib_kSortString),
|
|
AB_Column_kTiff = AB_Attrib_AsStdColUid(AB_Attrib_kTiff),
|
|
AB_Column_kTz = AB_Attrib_AsStdColUid(AB_Attrib_kTz),
|
|
AB_Column_kUid = AB_Attrib_AsStdColUid(AB_Attrib_kUid),
|
|
AB_Column_kVersion = AB_Attrib_AsStdColUid(AB_Attrib_kVersion),
|
|
AB_Column_kVoice = AB_Attrib_AsStdColUid(AB_Attrib_kVoice)
|
|
|
|
} AB_Column_eUid;
|
|
|
|
|
|
AB_PUBLIC_API(const char*) /* abcolumn.c */
|
|
AB_ColumnUid_AsString(ab_column_uid inStandardColumnUid, AB_Env* ev);
|
|
|
|
AB_PUBLIC_API(ab_column_uid) /* abcolumn.c */
|
|
AB_String_AsStandardColumnUid(const char* inStandardColumnName, AB_Env* ev);
|
|
|
|
AB_PUBLIC_API(ab_column_count) /* abtable.cpp */
|
|
AB_Table_GetColumnLayout(const AB_Table* self, AB_Env* ev,
|
|
AB_Column* outVector, ab_column_count inSize,
|
|
ab_column_count* outLength);
|
|
/*- GetColumnLayout fills the vector of AB_Column instances with
|
|
descriptions of the column layout for this table. (If this table does not
|
|
override settings from the address book, then this is the same as the
|
|
address book column layout.)
|
|
|
|
Note that columns described by GetColumnLayout are the default
|
|
columns added to AB_Row instances created by
|
|
AB_Table_MakeDefaultRow().
|
|
|
|
The outVector out parameter must be an array of at least inSize
|
|
AB_Column instances, but preferrably AB_Table_CountColumns() plus
|
|
one, because given enough instances the last column will be null
|
|
terminated by means of a zero pointer written in the sColumn_Name slot.
|
|
|
|
The actual number of columns (exactly equal to
|
|
AB_Table_CountColumns()) is returned from the method as the function
|
|
value. The number of columns actually described in outVector is
|
|
returned in outLength, and this is the same as the method value only
|
|
when inSize is greater than AB_Table_CountColumns(). If inSize is
|
|
greater than AB_Table_CountColumns(), then the column after the last
|
|
one described is null terminated with zero in the sColumn_Name slot.
|
|
|
|
Each column in the layout is described as follows. sColumn_Uid gets a
|
|
copy of the column uid returned from AB_Table_GetColumnId() for the
|
|
name written in sColumn_Name.
|
|
|
|
sColumn_Name gets a copy of the column name returned from
|
|
AB_Table_GetColumnName(). Callers must not modify or delete these
|
|
name strings, because these pointers are aliases to strings stored in a
|
|
dictionary within the self table instance, and modifying the strings
|
|
might have catastrophic effect.
|
|
|
|
sColumn_PrettyName gets either a null pointer (when the pretty name
|
|
and the real name are identical), or a string different from sColumn_Name
|
|
which the user prefers to see in the table display. Like sColumn_Name,
|
|
the storage for this string also belongs to self and must not be
|
|
modified, on pain of potential catastrophic effect.
|
|
|
|
sColumn_CanSort gets a boolean indicating whether the table can be
|
|
sorted by the column named by sColumn_Name. -*/
|
|
|
|
|
|
|
|
AB_PUBLIC_API(ab_column_count) /* abtable.cpp */
|
|
AB_Table_GetDefaultLayout(const AB_Table* self, AB_Env* ev,
|
|
AB_Column* outVector, ab_column_count inSize,
|
|
ab_column_count* outLength);
|
|
/*- GetDefaultLayout is nearly the same as
|
|
AB_Table_GetColumnLayout() except it returns the default layout used
|
|
for a new address book table, as opposed to a specific layour currently
|
|
in use by either this table or the actual address book table containing this
|
|
table. -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_ChangeColumnLayout(AB_Table* self, AB_Env* ev,
|
|
const AB_Column* inVector, ab_bool changeIndex);
|
|
|
|
/*- ChangeColumnLayout modifies the column layout of this table to be
|
|
equal to whatever is described in inVector, which must be null
|
|
terminated by means of a zero pointer in the final sColumn_Name slot of
|
|
the last column instance.
|
|
|
|
Note changing table columns will change the default set of columns
|
|
added to AB_Row instances created by subsequent calls to
|
|
AB_Table_MakeDefaultRow().
|
|
|
|
If changing the column layout implies a change of address book indexes,
|
|
then changeIndex must be true in order to actually cause this change to
|
|
occur, because removing an index can be a very expensive (slow)
|
|
operation. (We'll add asynchronous versions of this later.) -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_GetColumnAt(const AB_Table* self, AB_Env* ev,
|
|
AB_Column* outColumn, ab_column_pos inColPos);
|
|
|
|
/*- GetColumnAt gets the table's column layout information from column
|
|
position pos, which must be a one-based index from one to
|
|
AB_Table_CountColumns() (or otherwise false is returned and nothing
|
|
happens to the col parameter). -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_PutColumnAt(const AB_Table* self, AB_Env* ev,
|
|
const AB_Column* col, ab_column_pos pos, ab_bool changeIndex);
|
|
|
|
/*- PutColumnAt overwrites the table's column layout information at
|
|
column position pos, which must be a one-based index from one to
|
|
AB_Table_CountColumns() (or otherwise false is returned and nothing
|
|
happens to the table's column layout).
|
|
|
|
If the column named (sColumnName) already occurs at some other
|
|
position in the layout, then an error occurs. Otherwise the existing
|
|
column at pos is changed to col.
|
|
|
|
If the value of sColumn_CanSort implies a change of address book
|
|
indexes, then changeIndex must be true in order to actually cause this
|
|
change to occur, because adding or removing an index can be a very
|
|
expensive (slow) operation. (We'll add asynchronous versions of this
|
|
later.) -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_AddColumnAt(const AB_Table* self, AB_Env* ev,
|
|
const AB_Column* col, ab_column_pos pos, ab_bool changeIndex);
|
|
/*- AddColumnAt inserts new table column layout information at column
|
|
position pos, which must be a one-based index from one to
|
|
AB_Table_CountColumns() plus one (or otherwise false is returned and
|
|
nothing happens to the table's column layout).
|
|
|
|
If the column named (sColumnName) already occurs at some other
|
|
position in the layout, then an error occurs. Otherwise a new column at
|
|
pos is inserted in the layout.
|
|
|
|
If the value of sColumn_CanSort implies a change of address book
|
|
indexes, then changeIndex must be true in order to actually cause this
|
|
change to occur, because adding an index can be a very expensive
|
|
(slow) operation. (We'll add asynchronous versions of this later.) -*/
|
|
|
|
AB_PUBLIC_API(ab_column_pos) /* abtable.cpp */
|
|
AB_Table_CutColumn(const AB_Table* self, AB_Env* ev,
|
|
ab_column_uid col, ab_bool changeIndex);
|
|
/*- CutColumn removes an old column from the table column layout. The
|
|
col parameter must name a column currently in the layout (or otherwise
|
|
false is returned and nothing happens to the table's column layout).
|
|
|
|
If removing the column implies a change of address book indexes, then
|
|
changeIndex must be true in order to actually cause this change to
|
|
occur, because removing an index can be a very expensive (slow)
|
|
operation. (We'll add asynchronous versions of this later.) -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_CanSortByUid(const AB_Table* self, AB_Env* ev, ab_column_uid col);
|
|
/*- CanSortByUid indicates whether this table can sort rows by the
|
|
specified column uid col. Frontends might prefer to call
|
|
CanSortByName. -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_CanSortByName(const AB_Table* self, AB_Env* ev, const char* name);
|
|
/*- CanSortByName indicates whether this table can sort rows by the
|
|
specified column name.
|
|
|
|
CanSortByName is implemented by calling
|
|
AB_Table_CanSortByUid(self, ev,
|
|
AB_Table_GetColumnId(self, ev, name)); -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_SortByUid(const AB_Table* self, AB_Env* ev, ab_column_uid col);
|
|
/*- SortByUid sorts this table by the specified column col. If col is zero
|
|
this means make the table unsorted, which causes the table to order rows
|
|
in the most convenient internal form (which is by row uid for address
|
|
books, and some user specified order for mailing lists). -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_SortByName(const AB_Table* self, AB_Env* ev, const char* name);
|
|
/*- SortByName sorts this table by the specified column name. The
|
|
name parameter can be null, and this means make the table unsorted
|
|
(with respect to specific cell values). Making a table unsorted makes
|
|
particular sense for mailing lists.
|
|
|
|
SortByName is implemented by calling
|
|
AB_Table_SortByUid(self, ev, AB_Table_GetColumnId(self,
|
|
ev, name)); -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_SortFoward(const AB_Table* self, AB_Env* ev, ab_bool inAscend);
|
|
/*- If inAscend is true, arrange sorted rows in ascending order,
|
|
and otherwise arrange sorted rows in descending order -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_GetSortFoward(const AB_Table* self, AB_Env* ev);
|
|
/*- Return whether rows are arranged in ascending order -*/
|
|
|
|
AB_PUBLIC_API(ab_column_uid) /* abtable.cpp */
|
|
AB_Table_GetSortColumn(const AB_Table* self, AB_Env* ev);
|
|
/*- GetSortColumn returns the column currently used by the table for
|
|
sorting. Zero is returned when this table is currently unsorted (and also
|
|
when any error occurs). Unsorted tables might be common for mailing
|
|
lists. -*/
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abtable.cpp */
|
|
AB_Table_AcquireSortedTable(AB_Table* self, AB_Env* ev,
|
|
ab_column_uid newSortColumn);
|
|
/*- AcquireSortedTable returns a new table instance that has the same
|
|
content as the old table, but sorts on a different column. This is similar
|
|
to AB_Table_SortByUid(), but lets one have two different views of the
|
|
same table with different sortings.
|
|
|
|
If newSortColumn is zero this means return an unsorted table. If
|
|
newSortColumn is the same value as the current sorting returned by
|
|
AB_Table_GetSortColumn(), this means the returned table might be
|
|
exactly the same AB_Table instance as self. However, it will have been
|
|
acquired one more time, so self and the returned table act as if refcounted
|
|
separately even if they are the same table instance.
|
|
|
|
The caller must eventually release the returned table by calling
|
|
AB_Table_Release(), and then make sure not to refer to this table again
|
|
after released because it might be destroyed. -*/
|
|
|
|
#define AB_Table_AcquireUnsortedTable(table,ev) \
|
|
AB_Table_AcquireSortedTable(table,ev, /*unsorted*/ 0)
|
|
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
/* ----- ----- ----- ----- Search ----- ----- ----- ----- */
|
|
|
|
|
|
AB_PUBLIC_API(ab_row_uid) /* abtable.cpp */
|
|
AB_Table_FindFirstRowWithPrefix(AB_Table* self, AB_Env* ev,
|
|
const char* cellValuePrefix, ab_column_uid inColumnUid);
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abtable.cpp */
|
|
AB_Table_AcquireSearchTable(AB_Table* self, AB_Env* ev,
|
|
const char* cellValue, const ab_column_uid* inColumnVector);
|
|
/*- AcquireSearchTable returns a table giving the non-persistent results of
|
|
a search for cellValue in one or more columns of table self. The
|
|
columns to search are given in the array specified by inColumnVector
|
|
which should be null-terminated with a zero ab_column_uid value after
|
|
the last column to be searched.
|
|
|
|
The returned table will contain no duplicates, even if cellValue causes a
|
|
match in more than one column. The table content is virtual (not
|
|
persistent, and possibly listed only by indirect reference) and will not
|
|
exist after the table is released down to a zero refcount. (If the caller
|
|
wants a persistent table, the caller can make a new mailing list and iterate
|
|
over this table, adding all rows to the new mailing list.)
|
|
|
|
The caller must eventually release the returned table by calling
|
|
AB_Table_Release(), and then make sure not to refer to this table again
|
|
after released because it might be destroyed. (Debug builds might keep
|
|
around "destroyed" tables for a time to detect invalid access after ref
|
|
counts reach zero.) -*/
|
|
|
|
|
|
/* ----- ----- ----- ----- Rows ----- ----- ----- ----- */
|
|
|
|
|
|
/*- (The notion of row replaces both the old notions of entry and tuple. In
|
|
more detail, ab_row_uid replaces ABID, and AB_Row replaces
|
|
HgAbTuple. Nothing replaces HgAbSchema which simply goes away
|
|
because this behavior is folded into AB_Row. We could introduce the idea
|
|
of a meta-row to replace schema, but this is really just an performance
|
|
issue and we can hide these details from the FEs.)
|
|
|
|
A persistent row is identified by its uid, ab_row_uid, but callers can
|
|
only read and write such persistent objects by means of a runtime object
|
|
named AB_Row which can describe the content of a persisent row.
|
|
AB_Row denotes a transient session object and not a persistent object.
|
|
Any given instance of AB_Row has no associated ab_row_uid because
|
|
the runtime object is not intended to have a close association with a
|
|
single persisent row.
|
|
|
|
However, each AB_Row instance is associated with a specific instance of
|
|
AB_Table (even though this could be avoided) because this runtime
|
|
relationship happens to be convenient, and causes no awkwardness in
|
|
the interfaces. AB_Row can effectively be considered a view onto the
|
|
collection of persisent rows inside a given table, except AB_Row is not
|
|
focused on a specific row in the table. -*/
|
|
|
|
#ifndef AB_Row_typedef
|
|
typedef struct AB_Row AB_Row;
|
|
#define AB_Row_typedef 1
|
|
#endif
|
|
|
|
/*- AB_Row is an abstract data type. You don't know its internal structure.
|
|
All that is known about this class is the methods that use this type as an
|
|
argument or return value. -*/
|
|
|
|
enum {
|
|
AB_Row_kFaultNullMethods = /*i*/ AB_Fault_kRow, /* 300 */
|
|
AB_Row_kFaultWrongMethodTag, /*i*/ /* 301 */
|
|
AB_Row_kFaultNotRowUid, /*i*/ /* 302 */
|
|
AB_Row_kFaultNullTable, /*i*/ /* 303 */
|
|
AB_Row_kFaultOutOfMemory, /*i*/ /* 304 */
|
|
AB_Row_kFaultNonStandardColumn, /*i*/ /* 305 */
|
|
AB_Row_kFaultCountNotUnderSize, /*i*/ /* 306 */
|
|
AB_Row_kFaultNotOpen /*i*/ /* 307 */
|
|
};
|
|
|
|
AB_PUBLIC_API(ab_row_count) /* abtable.cpp */
|
|
AB_Table_AddAllRows(AB_Table* self, AB_Env* ev,
|
|
const AB_Table* other);
|
|
/*- AddAllRows adds all the rows in other to self, as if by iterating over
|
|
all rows in other and adding them one at a time with
|
|
AB_Table_AddRow(). -*/
|
|
|
|
|
|
AB_PUBLIC_API(ab_row_uid)
|
|
AB_Table_CopyRow(AB_Table* self, AB_Env* cev,
|
|
const AB_Table* inOther, ab_row_uid inRowUid);
|
|
/*- copy row inRowUid from inOther to this table -*/
|
|
|
|
AB_PUBLIC_API(ab_row_pos) /* abtable.cpp */
|
|
AB_Table_AddRow(AB_Table* self, AB_Env* ev, ab_row_uid row);
|
|
/*- AddRow aliases an existing row in the address book containing table
|
|
self (see AB_Table_GetBookTable()) so this table also contains this
|
|
row. If self already contains this row, nothing happens and false is
|
|
returned. If row does not denote a row in the address book, an error
|
|
occurs and zero is returned. (The error is indicated by
|
|
AB_Env_GetError().)
|
|
|
|
If self did not previously contain row, it is added and true is returned.
|
|
This is a way to alias an existing row into a new location, rather than
|
|
creaing a new persistent row. (New persistent rows are created with
|
|
AB_Row_NewTableRowAt().) -*/
|
|
|
|
AB_PUBLIC_API(ab_row_pos) /* abtable.cpp */
|
|
AB_Table_CutRow(AB_Table* self, AB_Env* ev, ab_row_uid row);
|
|
/*- CutRow removes the indicated row from the table. This does not
|
|
actually destroy the row unless this was the last reference to the row.
|
|
False is returned when the table did not previously contain row (but it's
|
|
okay to attempt cutting it again because the same desired result obtains
|
|
when the row is not in the table afterwards). -*/
|
|
|
|
AB_PUBLIC_API(ab_row_count) /* abtable.cpp */
|
|
AB_Table_CutRowRange(AB_Table* self, AB_Env* ev, ab_row_pos p, ab_row_count c);
|
|
/*- CutRow removes the indicated set of c rows from the table, starting
|
|
at one-based position p. This does not actually destroy the rows unless
|
|
they were the last references to the rows. -*/
|
|
|
|
AB_PUBLIC_API(ab_row_pos) /* abtable.cpp */
|
|
AB_Table_DestroyRow(AB_Table* self, AB_Env* ev, ab_row_uid row);
|
|
/*- DestroyRow removes the indicated row from this table and from
|
|
every other table containing the same row. False is returned when the
|
|
containing address book did not previously contain row anywhare (but
|
|
it's okay to attempt destroying it again because the same desired result
|
|
obtains when the row is not in the table afterwards). An error might
|
|
occur if the table can determine that row was never a valid row inside
|
|
the address book (perhaps the size of the uid indicates it has never been
|
|
assigned). -*/
|
|
|
|
AB_PUBLIC_API(ab_row_count) /* abtable.cpp */
|
|
AB_Table_CountRows(const AB_Table* self, AB_Env* ev);
|
|
/*- CountRows returns the number of rows in the table. (In other words,
|
|
how many entries does this address book or mailing list contain?) -*/
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abtable.cpp */
|
|
AB_Table_AcquireListsTable(AB_Table* self, AB_Env* ev);
|
|
/*- AcquireListsTable -*/
|
|
|
|
|
|
|
|
AB_PUBLIC_API(ab_row_count) /* abtable.cpp */
|
|
AB_Table_CountRowParents(const AB_Table* self, AB_Env* ev,
|
|
ab_row_uid id);
|
|
/*- CountRowParents returns the number of parent tables that contain the
|
|
row known by id. If zero, this means id does not exist because no
|
|
row corresponds to this uid. If more than one, this means that more than
|
|
one table contains an alias to this row. The value returned by
|
|
CountRowParents is effectively the persistent reference count for row
|
|
id. -*/
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abtable.cpp */
|
|
AB_Table_AcquireRowParentsTable(const AB_Table* self, AB_Env* ev,
|
|
ab_row_uid id);
|
|
/*- AcquireRowParentsTable returns a table representing the collection of
|
|
tables that contain the row known by id. A null pointer is returned
|
|
when any problem occurs (such as id not existing (i.e. zero
|
|
AB_Table_CountRowParents())).
|
|
|
|
The caller must eventually release the table by calling
|
|
AB_Table_Release(), and then make sure not to refer to this table again
|
|
after released because it might be destroyed. (Debug builds might keep
|
|
around "destroyed" tables for a time to detect invalid access after ref
|
|
counts reach zero.) -*/
|
|
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
AB_PUBLIC_API(ab_row_count) /* abtable.cpp */
|
|
AB_Table_CountRowChildren(const AB_Table* self, AB_Env* ev,
|
|
ab_row_uid id);
|
|
/*- CountRowChildren returns the number of children rows in the row
|
|
known by id. When this number is positive the row is a table.
|
|
Otherwise when zero the row is simply a row. -*/
|
|
|
|
#define AB_Table_IsRowTable(t,ev,row) \
|
|
(AB_Table_CountRowChildren(t,ev,row) != 0)
|
|
/*- IsRowTable returns whether the row known by row is a table.-*/
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abtable.cpp */
|
|
AB_Table_AcquireRowChildrenTable(const AB_Table* self, AB_Env* ev,
|
|
ab_row_uid tableId);
|
|
/*- AcquireRowChildrenTable returns a table representing the set of rows
|
|
inside the table known by tableId. Typically tableId is a mailing list
|
|
and the returned table shows the content of this mailing list. A null
|
|
pointer is returned when any problem occurs.
|
|
|
|
If tableId was previously not a table (because it had no children and so
|
|
AB_Table_IsRowTable() returns false), then the table returned is
|
|
empty. However, when the caller adds any row to this table, then
|
|
tableId becomes a table as a result. In other words, any row can be
|
|
made a mailing list by adding children, and this is done by acquiring the
|
|
row's children table and adding some children. Presto, changeo, now
|
|
the row is a table.
|
|
|
|
The caller must eventually release the table by calling
|
|
AB_Table_Release(), and then make sure not to refer to this table again
|
|
after released because it might be destroyed. (Debug builds might keep
|
|
around "destroyed" tables for a time to detect invalid access after ref
|
|
counts reach zero.) -*/
|
|
|
|
AB_PUBLIC_API(ab_row_uid) /* abtable.cpp */
|
|
AB_Table_GetRowAt(const AB_Table* self, AB_Env* ev, ab_row_pos p);
|
|
/*- GetRowAt returns the uid of the row at position p, where each row in
|
|
a table has a position from one to AB_Table_RowCount(). (One-based
|
|
indexes are used rather than zero-based indexes, because zero is
|
|
convenient for indicating when a row is not inside a table.) -*/
|
|
|
|
AB_PUBLIC_API(ab_row_count) /* abtable.cpp */
|
|
AB_Table_GetRows(const AB_Table* self, AB_Env* ev,
|
|
ab_row_uid* outVector, ab_row_count inSize, ab_row_pos pos);
|
|
/*- GetRows is roughly equivalent to calling AB_Table_GetRowAt()
|
|
inSize times. It is a good way to read a contiguous sequence of row
|
|
uids starting at position pos inside the table.
|
|
|
|
At most inSize uids are written to outVector, and the actual number
|
|
written there is returned as the value of function. The only reason why
|
|
fewer might be written is if fewer than inSize rows are in the table
|
|
starting at position pos.
|
|
|
|
Remember that pos is one-based, so one is the position of the first row
|
|
and AB_Table_CountRows() is the position of the last. -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abtable.cpp */
|
|
AB_Table_DoesSortRows(const AB_Table* self, AB_Env* ev);
|
|
/*- DoesSortRows returns whether table self maintains its row collection
|
|
in sorted order. Presumably this is always true for address books
|
|
(AB_Type_kAddressBookTable) but always false for mailing lists
|
|
(AB_Type_kMailingListTable). At least this would be consistent with
|
|
4.0 behavior.
|
|
|
|
DoesSortRows is equivalent to the expression
|
|
(AB_Table_GetSortColumn()!=0).
|
|
|
|
We might want to permit mailing lists to sort rows by cell values, just
|
|
like address books do. But in that case an unsorted representation should
|
|
be kept so users can keep list recipients in a preferred order. (A user
|
|
specified ordering might be important for social constraints in showing
|
|
proper acknowledgement to individuals according to some ranking
|
|
scheme.)
|
|
|
|
If we decide to sort mailing lists, the sorting will likely be maintained in
|
|
memory, as opposed to persistently. (Users with huge mailing lists
|
|
should use a separate address book for this purpose.) This would let
|
|
users easily revert to the original unsorted view of a list.
|
|
|
|
Getting a sorted interface to a list is done with
|
|
AB_Table_AcquireSortedTable(), and getting the unsorted version of
|
|
a list is done with AB_Table_AcquireUnsortedTable(). -*/
|
|
|
|
AB_PUBLIC_API(ab_row_pos) /* abtable.cpp */
|
|
AB_Table_RowPos(const AB_Table* self, AB_Env* ev, ab_row_uid id);
|
|
/*- RowPos returns the position of the row known by id, where each row
|
|
in a table has a position from one to AB_Table_RowCount(). Zero is
|
|
returned when this row is not inside the table. -*/
|
|
|
|
#define AB_Table_HasRow(t,ev,row) (AB_Table_RowPos(t,ev,row) != 0)
|
|
/*- HasRow returns whether table self contains the indicated row.-*/
|
|
|
|
AB_PUBLIC_API(ab_row_pos) /* abtable.cpp */
|
|
AB_Table_ChangeRowPos(const AB_Table* self, AB_Env* ev,
|
|
ab_row_uid existingRow, ab_row_pos toNewPos);
|
|
/*- ChangeRowPos moves the row known by existingRow to new
|
|
position toNewPos, provided AB_Table_DoesSortRows() is true.
|
|
Otherwise ChangeRowPos does nothing (and returns false) if the table
|
|
is in sorted order, or if existingRow is not in the table
|
|
(AB_Table_HasRow() returns false).
|
|
|
|
Specifically, ChangeRowPos is expected to be useful for mailing list
|
|
tables (AB_Type_kMailingListTable), but not useful for address book
|
|
tables (AB_Type_kAddressBookTable) nor useful for some other table
|
|
types (e.g. AB_Type_kSearchResultTable).
|
|
|
|
If FEs wish, they need not worry about this restriction, but simply let
|
|
users see that dragging rows in mailing lists is useful, but dragging rows
|
|
in address books has no effect. It does not seem feasible to prevent users
|
|
from attempting to drag within an address book, because FEs will not
|
|
know whether the user intends to drop elsewhere, say in another address
|
|
book. FEs might want to figure out whether a drop makes sense in the
|
|
same table, but they can simply call ChangeRowPos and find out
|
|
(through both the return value and notifications) whether it has any
|
|
effect. -*/
|
|
|
|
AB_PUBLIC_API(ab_column_count) /* abtable.cpp */
|
|
AB_Table_CountRowCells(const AB_Table* self, AB_Env* ev,
|
|
ab_row_uid id);
|
|
/*- CountRowCells returns the number of cells in the row known by id,
|
|
which means the number of columns that have non-empty values in the
|
|
row. (In other words, how many attributes does this entry have?) -*/
|
|
|
|
AB_PUBLIC_API(AB_Row*) /* abtable.cpp */
|
|
AB_Table_MakeDefaultRow(AB_Table* self, AB_Env* ev);
|
|
/*- MakeDefaultRow creates a runtime description of a row (but not a
|
|
persistent row). (Creating a persistent table row is done with
|
|
AB_Row_NewTableRowAt().) This instance must be deallocated later with
|
|
AB_Row_Free().
|
|
|
|
This instance of AB_Row will already have cells corresponding to the
|
|
columns used by the table (see AB_Table_GetColumnLayout()), so
|
|
frontends that intend to use this row to display columns from the table
|
|
will no need not do any more work before calling
|
|
AB_Row_ReadTableRow() to read row content from the table. -*/
|
|
|
|
AB_PUBLIC_API(AB_Row*) /* abtable.cpp */
|
|
AB_Table_MakeRow(AB_Table* self, AB_Env* ev, const AB_Cell* inVector);
|
|
/*- MakeRow creates a runtime description of a row (but not a persistent
|
|
row) with N cells as described by the array of (at least) N+1 cells
|
|
pointed to by inVector. Only the sCell_Column and sCell_Size slots
|
|
matter. Other cell slots are ignored. The length of the inVector array is
|
|
inferred by the first cell that contains zero in the sCell_Column slot,
|
|
which is used for null termination.
|
|
|
|
If the first N cells of inVector have nonzero sCell_Column slots, then
|
|
those first N cells must also have nonzero sCell_Size slots, or else an
|
|
error occurs.
|
|
|
|
The sCell_Column slot values should be all distinct, without duplicate
|
|
columns. If inVector has duplicate columns, the last one wins and no
|
|
error occurs (so callers should check before calling if they care).
|
|
|
|
After a row is created, more cells can be added with
|
|
AB_Row_AddCells(). -*/
|
|
|
|
AB_PUBLIC_API(AB_Row*) /* abtable.cpp */
|
|
AB_Table_MakeRowFromColumns(AB_Table* self, AB_Env* ev,
|
|
const AB_Column* inColumns);
|
|
/*- MakeRowFromColumns is just like AB_Table_MakeRow() except that
|
|
sColumn_Uid and sColumn_CellSize slots are used (instead of
|
|
sCell_Column and sCell_Size) and the vector is null terminated with a
|
|
zero in sColumn_Uid. -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
AB_PUBLIC_API(AB_Row*) /* abtable.cpp */
|
|
AB_Table_MakePersonRow(AB_Table* self, AB_Env* ev);
|
|
/*- MakePersonRow creates a runtime description of a row (but not a
|
|
persistent row) that seems most suited for editing a description of a
|
|
person. This is like calling AB_Table_MakeRow() with the cell vector
|
|
returned by AB_Table_GetPersonCells(). -*/
|
|
|
|
AB_PUBLIC_API(AB_Row*) /* abtable.cpp */
|
|
AB_Table_MakePersonList(AB_Table* self, AB_Env* ev);
|
|
/*- MakePersonList creates a runtime description of a row (but not a
|
|
persistent row) that seems most suited for editing a description of a
|
|
mailing list. This is like calling AB_Table_MakeRow() with the cell vector
|
|
returned by AB_Table_GetListCells(). -*/
|
|
|
|
|
|
|
|
AB_PUBLIC_API(ab_cell_count) /* abtable.cpp */
|
|
AB_Table_GetPersonCells(const AB_Table* self, AB_Env* ev,
|
|
AB_Cell* outVector, ab_cell_count inSize, ab_cell_count* outLength);
|
|
/*- GetPersonCells returns a copy of the standard cells for a person in
|
|
cell array outVector. This cell vector is address book specific because
|
|
column uids in the sCell_Column slots have address book scope. The
|
|
actual number of standard cells is returned as the function value, but the
|
|
size of outVector is assumed to be inSize, so no more than inSize
|
|
cells will be written to outVector. The actual number of cells written is
|
|
returned in outLength (unless outLength is a null pointer to suppress
|
|
this output).
|
|
|
|
If inSize is greater than the number of cells, N, then outVector[N] will
|
|
be null terminated by placing all zero values in all the cell slots.
|
|
|
|
All the sCell_Content slots will be null pointers because these cells
|
|
will not represent actual storage in a row. GetPersonCells is expected
|
|
to be used in the implementation of methods like
|
|
AB_Table_MakePersonRow(). -*/
|
|
|
|
AB_PUBLIC_API(ab_cell_count) /* abtable.cpp */
|
|
AB_Table_GetListCells(const AB_Table* self, AB_Env* ev,
|
|
AB_Cell* outVector, ab_cell_count inSize, ab_cell_count* outLength);
|
|
/*- GetListCells returns a copy of the standard cells for a mailing list
|
|
in cell array outVector. This cell vector is address book specific because
|
|
column uids in the sCell_Column slots have address book scope. The
|
|
actual number of standard cells is returned as the function value, but the
|
|
size of outVector is assumed to be inSize, so no more than inSize
|
|
cells will be written to outVector. The actual number of cells written is
|
|
returned in outLength (unless outLength is a null pointer to suppress
|
|
this output).
|
|
|
|
If inSize is greater than the number of cells, N, then outVector[N] will
|
|
be null terminated by placing all zero values in all the cell slots.
|
|
|
|
All the sCell_Content slots will be null pointers because these cells
|
|
will not represent actual storage in a row. GetListCells is expected to be
|
|
used in the implementation of methods like
|
|
AB_Table_MakePersonList(). -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
|
|
AB_PUBLIC_API(AB_Row*) /* abrow.c */
|
|
AB_Row_MakeRowClone(const AB_Row* self, AB_Env* ev);
|
|
/*- MakeRowClone allocates a duplicate of row self with exactly the same
|
|
table, cell structure, and cell content. A caller might use this method to
|
|
create a copy of a row prior to making changes when the original row
|
|
must be kept intact. -*/
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abrow.c */
|
|
AB_Row_Acquire(AB_Row* self, AB_Env* ev);
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abrow.c */
|
|
AB_Row_Release(AB_Row* self, AB_Env* ev);
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_CopyRowContent(AB_Row* self, AB_Env* ev, const AB_Row* other);
|
|
/*- CopyRowContent makes all cells in self contain the same content as
|
|
corresponding cells (with the same sCell_Column) in other. This
|
|
affects cell content only, and does not change the cell structure of self at
|
|
all, so number and size of cells does not change. If a cell in self is too
|
|
small to receive all content in other, the content is truncated rather than
|
|
enlarging the cell (in contrast to AB_Row_BecomeRow()). -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_BecomeRowClone(AB_Row* self, AB_Env* ev, const AB_Row* other);
|
|
/*- BecomeRowClone causes self to be a clone of other, with exactly the
|
|
same cell structure and cell content. (If self and other belong to
|
|
different tables, then self changes its table to that of other.) -*/
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abrow.c */
|
|
AB_Row_GetTable(const AB_Row* self, AB_Env* ev);
|
|
/*- GetTable returns the table that created this row.
|
|
(Null returns on error.)-*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_ChangeTable(AB_Row* self, AB_Env* ev, AB_Table* table);
|
|
/*- ChangeTable sets the table for this row to table (and this does any
|
|
necessary table reference counting). -*/
|
|
|
|
AB_PUBLIC_API(ab_row_uid) /* abrow.c */
|
|
AB_Row_NewTableRowAt(const AB_Row* self, AB_Env* ev, ab_row_pos pos);
|
|
/*- New creates a new row in the table at position pos by writing the
|
|
cells specified by this row. Zero is returned on error (zero is never a
|
|
valid uid), and the specific error is indicated by AB_Env_GetError().
|
|
|
|
The position pos can be any value, not just one to
|
|
AB_Table_CountRows(). If zero, this means put the new row wherever
|
|
seems best. If greater than the number of rows, it means append to the
|
|
end. If the table is currently sorted in some order, pos is ignored and
|
|
the new row is goes in sorted position. -*/
|
|
|
|
#define AB_Row_NewTableRow(table,ev) AB_Row_NewTableRowAt(table,ev,0)
|
|
/*- NewTableRow is just like AB_Row_NewTableRowAt() except with the
|
|
position argument curried with the constant value zero, which is ignored
|
|
anyway by address books, but for mailing lists might cause the new row
|
|
to be, say, appended after the last existing row. -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_ReadTableRowAt(AB_Row* self, AB_Env* ev, ab_row_pos pos);
|
|
/*- ReadTableRowAt reads the row in the table at postion pos, filling cell
|
|
values from the persistent content for the row found in the table. All cells
|
|
are given values read from row id in the table, and this includes making
|
|
cells empty when the persistent row has no such cell value. -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_ReadTableRow(AB_Row* self, AB_Env* ev, ab_row_uid id);
|
|
/*- ReadTableRow reads the row in the table known by id, filling cell
|
|
values from the persistent content for the row found in the table. All cells
|
|
are given values read from row id in the table, and this includes making
|
|
cells empty when the persistent row has no such cell value. If cells in
|
|
self are too small to read the entire content from the table, only the -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_GrowToReadEntireTableRow(AB_Row* self, AB_Env* ev,
|
|
ab_row_uid id, ab_cell_size maxCellSize);
|
|
/*- GrowToReadEntireTableRow reads the row in the table known by id,
|
|
filling cell values from the persistent content for the row found in the
|
|
table. All cells are given values read from row id in the table, and this
|
|
includes making cells empty when the persistent row has no such cell
|
|
value.
|
|
|
|
In contrast to AB_Row_ReadTableRow() which does not change cell
|
|
structure to read content from the table, GrowToReadEntireTableRow
|
|
will add cells as needed and grow the size of cells as needed in order to
|
|
hold every byte of every persistent cell value. In other words,
|
|
GrowToReadEntireTableRow will read the entire persistent content of
|
|
the table row while growing to the extent necessary to capture all this
|
|
content.
|
|
|
|
The maxCellSize parameter can be zero to cause it to be ignored, but if
|
|
nonzero, maxCellSize is used to cap cell growth so to no more than
|
|
maxCellSize. This lets callers attempt to accomodate all persistent
|
|
content up to some reasonable threshold over which the caller might no
|
|
longer care whether more cell content is present. So if a persistent value
|
|
is too big to fit in a cell, and is also bigger than maxCellSize, then the
|
|
cell has its size increased only to maxCellSize before reading the cell
|
|
value. -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
|
|
AB_PUBLIC_API(ab_row_pos) /* abrow.c */
|
|
AB_Row_UpdateTableRow(const AB_Row* self, AB_Env* ev, ab_row_uid id);
|
|
/*- UpdateTableRow writes part of the row known by id in the table,
|
|
updating all cells with non-empty content in self, so that empty cells in
|
|
self have no effect on the persistent row in the table. Also, cells not
|
|
described at all in self are not touched at all in the table. -*/
|
|
|
|
AB_PUBLIC_API(ab_row_pos) /* abrow.c */
|
|
AB_Row_ResetTableRow(const AB_Row* self, AB_Env* ev, ab_row_uid id);
|
|
/*- ResetTableRow writes all of the row known by id in the table, updating
|
|
all of the table row cells, whether they are described by self or not.
|
|
Cells not in self and empty cells in self are removed from row id.
|
|
Non-empty cells in self have their values written to row id so that each
|
|
table row cell contains only the content described by self. -*/
|
|
|
|
|
|
/* ----- ----- ----- ----- Cells ----- ----- ----- ----- */
|
|
|
|
|
|
#ifndef AB_Cell_typedef
|
|
typedef struct AB_Cell AB_Cell;
|
|
#define AB_Cell_typedef 1
|
|
#endif
|
|
|
|
struct AB_Cell { /* interface to buffer a single row attribute */
|
|
ab_column_uid sCell_Column; /* the column associated with this row cell */
|
|
ab_cell_size sCell_Size; /* the size of sCell_Content in bytes */
|
|
ab_cell_length sCell_Length; /* the length of content in sCell_Content */
|
|
ab_cell_extent sCell_Extent; /* the amount of persistent cell content */
|
|
char* sCell_Content; /* buffer to hold cell content */
|
|
};
|
|
|
|
|
|
enum AB_Cell_eError { /* AB_Cell errors */
|
|
AB_Cell_kFaultOutOfMemory = /*i*/ AB_Fault_kCell, /* 500 */
|
|
AB_Cell_kFaultBadColumnUid, /*i*/ /* 501 */
|
|
AB_Cell_kFaultNullContent, /*i*/ /* 502 */
|
|
AB_Cell_kFaultZeroCellSize, /*i*/ /* 503 */
|
|
AB_Cell_kFaultSizeExceedsMax, /*i*/ /* 504 */
|
|
AB_Cell_kFaultSizeTooSmall, /*i*/ /* 505 */
|
|
AB_Cell_kFaultLengthExceedsSize /*i*/ /* 506 */
|
|
};
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_ClearAllCells(AB_Row* self, AB_Env* ev);
|
|
/*- ClearAllCells makes all the cells in this row empty of content. -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_WriteCell(AB_Row* self, AB_Env* ev,
|
|
const char* content, ab_column_uid col);
|
|
/*- WriteCell ensures that row self has a cell with column col and sets
|
|
the content of this cell to content, with length strlen(content). If
|
|
the row did not previously have such a cell, it gets one just as if
|
|
AB_Row_AddCell() had been called. Also, if the length of content is
|
|
greater than the old size of the cell, the cell's size is increased to make it
|
|
big enough to hold all the content (also just as if AB_Row_AddCell() had
|
|
been called).
|
|
|
|
(WriteCell is implemented by calling AB_Row_PutCell().) -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_PutCell(AB_Row* self, AB_Env* ev, const AB_Cell* c);
|
|
/*- PutCell is the internal form of WriteCell which assumes the length of
|
|
the content to write is already known. Only the sCell_Content,
|
|
sCell_Length, and sCell_Column slots are used from c. -*/
|
|
|
|
AB_PUBLIC_API(ab_cell_count) /* abrow.c */
|
|
AB_Row_CountCells(const AB_Row* self, AB_Env* ev);
|
|
/*- CountCells returns the number of cells in this row. -*/
|
|
|
|
AB_PUBLIC_API(ab_cell_count) /* abrow.c */
|
|
AB_Row_GetCells(const AB_Row* self, AB_Env* ev,
|
|
AB_Cell* outVector, ab_cell_count inSize, ab_cell_count* outLength);
|
|
/*- GetCells returns a copy of the row's cells in outVector. The actual
|
|
number of row cells is returned as the function value, but the size of
|
|
outVector is assumed to be inSize, so no more than inSize cells will
|
|
be written to outVector. The actual number of cells written is returned
|
|
in outLength (unless outLength is a null pointer to suppress this
|
|
output).
|
|
|
|
If inSize is greater than the number of cells, N, then outVector[N] will
|
|
be null terminated by placing all zero values in all the cell slots.
|
|
|
|
Each sCell_Content slot points to space owned by the row. This space
|
|
might change whenever the row changes, so callers must not cause the
|
|
row to change while cell content is still being accessed. -*/
|
|
|
|
/* ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- */
|
|
|
|
|
|
AB_PUBLIC_API(const AB_Cell*) /* abrow.c */
|
|
AB_Row_GetCellAt(const AB_Row* self, AB_Env* ev, ab_cell_pos pos);
|
|
/*- GetCellAt returns a pointer to a AB_Cell inside the self instance. This
|
|
is a potentially dangerous exposure of internal structure for the sake of
|
|
performance. Callers are expected to use this cell only long enough to
|
|
see cell slots like sCell_Content that might be needed, and then forget
|
|
this pointer as soon as possible.
|
|
|
|
Whenever the row is changed so that cell structure is modified, this
|
|
AB_Cell instance might no longer exist afterwards. So using this cell
|
|
must be only of transient nature. Clients should call GetCellAt again
|
|
later, each time a cell is desired.
|
|
|
|
GetCellAt returns a null pointer if pos is zero, or if pos is greater
|
|
than the number of cells (AB_Row_CountCells()). The cells have
|
|
one-based positions numbered from one to the number of cells.
|
|
|
|
The cell returned must not be modified, on pain of undefined behavior.
|
|
Callers must not assume anything about adjacency of other cells in the
|
|
row. Cells might be stored discontiguously. -*/
|
|
|
|
AB_PUBLIC_API(const AB_Cell*) /* abrow.c */
|
|
AB_Row_GetColumnCell(const AB_Row* self, AB_Env* ev, ab_column_uid id);
|
|
/*- GetColumnCell is just like AB_Row_GetCellAt() except that the cell is
|
|
found by matching the column uid. If the row has no such column, then
|
|
a null pointer is returned. -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_AddCells(AB_Row* self, AB_Env* ev, const AB_Cell* inVector);
|
|
/*- AddCells changes the row's cell structure to include the cells described
|
|
in inVector which must be null terminated by a zero value in the
|
|
sCell_Column slot after the last cell to be added. Only the
|
|
sCell_Column and sCell_Size slots matter and other slots are ignored.
|
|
|
|
The sCell_Column slot values should be all distinct, without duplicate
|
|
columns. If inVector has duplicate columns, the last one wins and no
|
|
error occurs (so callers should check before calling if they care).
|
|
|
|
AddCells is implemented by calling AB_Row_AddCell(). -*/
|
|
|
|
#define AB_Cell_kMaxCellSize (32 * 1024)
|
|
/*- kMaxCellSize is the maximum size cell. It's main function is to sanity
|
|
check reasonable values for cell size passed to AB_Row_AddCell(), but
|
|
this is also effectively the largest piece of contiguous memory we want
|
|
to guarantee we can allocate in cross platform code. -*/
|
|
|
|
AB_PUBLIC_API(AB_Cell*) /* abrow.c */
|
|
AB_Row_AddCell(AB_Row* self, AB_Env* ev, ab_column_uid id, ab_cell_size size);
|
|
/*- AddCell gives the row another cell for column id which can hold size
|
|
substract one content bytes. Both id and size must be nonzero, and
|
|
id must denote a valid column in the address book, and size must be no
|
|
greater than AB_Cell_kMaxCellSize. If the cell known by id
|
|
previously existed, then it's size is changed to equal the maximum of
|
|
either the old size or the new size. (To shrink the size of a cell, remove
|
|
it first with AB_Row_CutCell() and then re-add the cell. The specified
|
|
size behavior here is most convenient for upgrading rows to hold bigger
|
|
content.) -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abrow.c */
|
|
AB_Row_CutCell(AB_Row* self, AB_Env* ev, ab_column_uid id);
|
|
/*- CutCell removes any cell identified by column uid id. True is returned
|
|
only if such a cell existed (and was removed). False returns when no
|
|
such cell was found (or if an error occurs). No error occurs from cutting
|
|
a cell which does not exist, because the desired end result -*/
|
|
|
|
AB_PUBLIC_API(char *) /* abrow.c */
|
|
AB_Row_AsVCardString(AB_Row* self, AB_Env* ev);
|
|
/*- returned string allocated by ab_Env::CopyString() which advertises
|
|
itself as using XP_ALLOC for space allocation. A null pointer is
|
|
typically returned in case of error. (It would not be that safe
|
|
to return an empty static string which could not be deallocated.) -*/
|
|
|
|
/* ----- ----- ----- ----- Stores ----- ----- ----- ----- */
|
|
|
|
#define AB_Store_kMinFootprint /*i*/ (48 * 1024)
|
|
#define AB_Store_kMinFootprintGrowth /*i*/ (32 * 1024)
|
|
|
|
#define AB_Store_kGoodFootprintSpace /*i*/ (512 * 1024)
|
|
#define AB_Store_kGoodFootprintGrowth /*i*/ (1024 * 1024)
|
|
|
|
#define AB_Store_kBigStartingFootprint /*i*/ (8 * 1024 * 1024)
|
|
#define AB_Store_kBigFootprintGrowth /*i*/ (4 * 1024 * 1024)
|
|
|
|
/* ````` making a new store instance (need AB_Env instance) ````` */
|
|
|
|
AB_PUBLIC_API(AB_Store*) /* abstore.cpp */
|
|
AB_Env_NewStore(AB_Env* self, const char* inFileName,
|
|
ab_num inTargetFootprint);
|
|
/*- Open and/or create a database named inFileName (which must
|
|
yield type AB_StoreType_kTable from AB_FileName_GetStoreType(),
|
|
or else an error occurs). -*/
|
|
|
|
/* ````` regarding file names for stores ````` */
|
|
|
|
typedef enum AB_Store_eType /*d*/ {
|
|
|
|
AB_StoreType_kUnknown = 0, /* unknown: cannot be opened or imported */
|
|
AB_StoreType_kTable = 1, /* use AB_Env_NewStore() to access store */
|
|
AB_StoreType_kImport = 2, /* import only using AB_Store_NewImportFile() */
|
|
AB_StoreType_kStale = 3, /* unsupported transient development format */
|
|
AB_StoreType_kFuture = 4 /* unsupported furture final format */
|
|
|
|
} AB_Store_eType;
|
|
|
|
AB_PUBLIC_API(AB_Store_eType) /* abstore.cpp */
|
|
AB_FileName_GetStoreType(const char* inFileName, AB_Env* ev);
|
|
/*- GetStoreType() returns an enum value that describes how the file
|
|
can be handled. Currently this is based on the file name itself, but
|
|
later this might also involve looking inside the file to examine the
|
|
bytes to determine correct usage. The file can only be opened and
|
|
used as an instance of AB_Store (using AB_Env_NewStore()) if the type
|
|
equals AB_StoreType_kTable, which means the store supports the table
|
|
interface. Otherwise, if the file type is AB_StoreType_kImport, this
|
|
means one should create a new database with an appropriate name (see
|
|
AB_FileName_MakeNativeName()), and import this file. (Or the new file
|
|
might already exist from earlier, openable with AB_Env_NewStore().)
|
|
Formats which cannot opened nor imported might be either "unknown"
|
|
or "stale" (AB_StoreType_kUnknown or AB_StoreType_kStale), where the
|
|
stale formats are recognizably retired transient development formats,
|
|
while unknown formats might still be importable by other means. When
|
|
a "future" format is detected which has not yet been implemented, the
|
|
type returned is AB_StoreType_kFuture, and presumably this means that
|
|
neither opening nor importing is feasible (like stale formats) but
|
|
that products with later versions should read the format.
|
|
|
|
The native format will be ".na2", but we can use transient development
|
|
formats before the final format with different suffixes like ".na0".
|
|
Later a ".na0" format will return AB_StoreType_kStale.
|
|
|
|
The imported formats will include ".ldi" and ".ldif" for LDIF, with
|
|
".htm" and ".html" for HTML. Later we'll support more formats.
|
|
|
|
The unknown file formats might still be importable using more general
|
|
purpose import code that can recognize a broader range of formats. -*/
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp */
|
|
AB_FileName_GetNativeSuffix(char* outFileNameSuffix8, AB_Env* ev);
|
|
/*- GetNativeSuffix() writes into outFileNameSuffix8 the file name
|
|
extension suffix (for example, ".na2") that is preferred for the
|
|
current native database format created for new database files. The
|
|
space should be at least eight characters in length for safety, though
|
|
in practice five bytes will be written: a period, followed by three
|
|
alphanumeric characters, followed by a null byte. Whenever one wishes
|
|
to make a new database, the filename for the database should end with
|
|
this string suffix. (Note that implementations might return more than
|
|
one string suffix, assuming the environment has access to prefs or some
|
|
other indication of which format to choose among possibilities.) -*/
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abstore.cpp */
|
|
AB_FileName_HasNativeSuffix(const char* inFileName, AB_Env* ev);
|
|
/*- HasNativeSuffix() returns true only if inFileName ends with a
|
|
suffix equal to that returned by AB_FileName_GetNativeSuffix(). -*/
|
|
|
|
AB_PUBLIC_API(const char*) /* abstore.cpp */
|
|
AB_FileName_FindSuffix(const char* inFileName);
|
|
/*- FindSuffix() returns the address of the last period "." in the
|
|
string inFileName, or null if no period is found at all. This method
|
|
is used to locate the suffix for comparison in HasNativeSuffix().
|
|
Typically file format judgments will be made on the three characters
|
|
that follow the final period in the filename. -*/
|
|
|
|
AB_PUBLIC_API(char*) /* abstore.cpp */
|
|
AB_FileName_MakeNativeName(const char* inFileName, AB_Env* ev);
|
|
/*- MakeNativeName() allocates a new string (which must be freed
|
|
later using XP_FREE()) for which AB_FileName_HasNativeSuffix()
|
|
is true. If inFileName already has the native suffix, the string
|
|
returned is a simple copy; otherwise the returned string appends
|
|
the value of AB_FileName_GetNativeSuffix() to the end. (Note that
|
|
the environment might select one of several format choices.) -*/
|
|
|
|
/* ````` destroying an old store instance (need AB_Env instance) ````` */
|
|
|
|
AB_API_IMPL(void) /* abstore.cpp */
|
|
AB_Env_DestroyStoreWithFileName(AB_Env* self, const char* inFileName);
|
|
/* DestroyStoreWithFileName() deletes the file from the file system
|
|
containing the store that would be opened if a store instance was
|
|
created using inFileName for the file name. This method is provided
|
|
to keep file destruction equally as abstract as the implicit file
|
|
creation occuring when a new store is created. Otherwise it would
|
|
be difficult to discard databases as easily as they are created. But
|
|
this method is dangerous in the sense that destruction of data is
|
|
definitely intended, so don't call this method unless the total
|
|
destruction of data in the store is what you have in mind. This
|
|
method does not attempt to verify the file contains a database before
|
|
destroying the file with name inFileName in whatever directory is
|
|
used to host the database files. Make sure you name the right file. */
|
|
|
|
|
|
/* ````` opening store CONTENT ````` */
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp */
|
|
AB_Store_OpenStoreContent(AB_Store* self, AB_Env* ev);
|
|
|
|
/* ````` closing store CONTENT (aborts unsaved changes) ````` */
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp */
|
|
AB_Store_CloseStoreContent(AB_Store* self, AB_Env* ev); /* abort */
|
|
|
|
/* ````` saving store CONTENT (commits unsaved changes) ````` */
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp */
|
|
AB_Store_SaveStoreContent(AB_Store* self, AB_Env* ev); /* commit */
|
|
|
|
/* ````` importing store CONTENT ````` */
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp */
|
|
AB_Store_ImportWithPromptForFileName(AB_Store* self, AB_Env* ev, MWContext* ioContext);
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp */
|
|
AB_Store_ImportEntireFileByName(AB_Store* self, AB_Env* ev, const char* inFileName);
|
|
/* ImportEntireFileByName() just calls ImportFileByName() with a
|
|
thumb instance intended to convey "all the file content". */
|
|
|
|
/* ````` exporting store CONTENT ````` */
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp */
|
|
AB_Store_ExportWithPromptForFileName(AB_Store* self, AB_Env* ev, MWContext* ioContext);
|
|
|
|
|
|
/* ````` thumbs ````` */
|
|
|
|
AB_PUBLIC_API(AB_Thumb*) /* abthumb.cpp */
|
|
AB_Store_NewThumb(AB_Store* self, AB_Env* ev, ab_row_count inRowLimit,
|
|
ab_num inFileByteCountLimit);
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abthumb.cpp */
|
|
AB_Thumb_IsProgressFinished(const AB_Thumb* self, AB_Env* ev);
|
|
|
|
AB_PUBLIC_API(void) /* abthumb.cpp */
|
|
AB_Thumb_SetPortingLimits(AB_Thumb* self, AB_Env* ev, ab_row_count inRowLimit,
|
|
ab_num inFileByteCountLimit);
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abthumb.cpp */
|
|
AB_Thumb_Acquire(AB_Thumb* self, AB_Env* ev);
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abthumb.cpp */
|
|
AB_Thumb_Release(AB_Thumb* self, AB_Env* ev);
|
|
|
|
/*| ImportProgress: return the current position in the import file, and also
|
|
**| the actual length of the import file in outFileLength, since this can be
|
|
**| used to show percentage progress through the import file. However, we
|
|
**| can only show progress through the current pass through the file, which
|
|
**| is returned in outPass (typically either 1 or 2 for first or second pass).
|
|
**|
|
|
**|| Note that when outPass turns over from 1 to 2, the progress through the
|
|
**| file will revert back to a smaller percentage of the file, so a progress
|
|
**| bar might want to reveal to users which pass is currently in progress.
|
|
|*/
|
|
AB_PUBLIC_API(ab_pos) /* abthumb.cpp */
|
|
AB_Thumb_ImportProgress(AB_Thumb* self, AB_Env* ev, ab_pos* outFileLength,
|
|
ab_count* outPass);
|
|
|
|
/*| ExportProgress: return the row position of the row that was last exported,
|
|
**| and also the total number of rows to be exported in outTotalRows, since this
|
|
**| can be used to show percentage progress through the export task.
|
|
|*/
|
|
AB_PUBLIC_API(ab_row_pos) /* abthumb.cpp */
|
|
AB_Thumb_ExportProgress(AB_Thumb* self, AB_Env* ev, ab_row_count* outTotalRows);
|
|
|
|
typedef enum AB_File_eFormat {
|
|
AB_File_kUnknownFormat = 0x3F3F3F3F, /* '????' */
|
|
AB_File_kLdifFormat = 0x6C646966, /* 'ldif' */
|
|
AB_File_kHtmlFormat = 0x68746D6C, /* 'html' */
|
|
AB_File_kXmlFormat = 0x61786D6C, /* 'axml' */
|
|
AB_File_kVCardFormat = 0x76637264, /* 'vcrd' */
|
|
AB_File_kBinaryFormat = 0x626E7279, /* 'bnry' */
|
|
AB_File_kNativeFormat = 0x6E617476 /* 'natv' current native format */
|
|
} AB_File_eFormat;
|
|
|
|
/*| ImportFileFormat: describe the current file format being imported
|
|
|*/
|
|
AB_PUBLIC_API(AB_File_eFormat) /* abthumb.cpp */
|
|
AB_Thumb_ImportFileFormat(AB_Thumb* self, AB_Env* ev);
|
|
|
|
/* ````` file-and-thumb based import and export ````` */
|
|
|
|
AB_PUBLIC_API(AB_File*) /* abstore.cpp */
|
|
AB_Store_NewImportFile(AB_Store* self, AB_Env* ev, const char* inFileName);
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abstore.cpp, true iff !AB_Thumb_IsProgressFinished() */
|
|
AB_Store_ContinueImport(AB_Store* self, AB_Env* ev, AB_File* ioFile,
|
|
AB_Thumb* ioThumb);
|
|
|
|
AB_PUBLIC_API(AB_File*) /* abstore.cpp */
|
|
AB_Store_NewExportFile(AB_Store* self, AB_Env* ev,
|
|
const char* inFileName);
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abstore.cpp, true iff !AB_Thumb_IsProgressFinished() */
|
|
AB_Store_ContinueExport(AB_Store* self, AB_Env* ev, AB_File* ioFile,
|
|
AB_Thumb* ioThumb);
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abfile.cpp */
|
|
AB_File_Acquire(AB_File* self, AB_Env* ev);
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abfile.cpp */
|
|
AB_File_Release(AB_File* self, AB_Env* ev);
|
|
|
|
|
|
/* ````` batching changes (these calls should nest okay) ````` */
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp, commit every inEventThreshold changes */
|
|
AB_Store_StartBatchMode(AB_Store* self, AB_Env* ev,
|
|
ab_num inEventThreshold);
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp */
|
|
AB_Store_EndBatchMode(AB_Store* self, AB_Env* ev);
|
|
|
|
|
|
/* ````` open/close content status querying ````` */
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abstore.cpp */
|
|
AB_Store_IsOpenStoreContent(AB_Store* self);
|
|
|
|
AB_PUBLIC_API(ab_bool) /* abstore.cpp */
|
|
AB_Store_IsShutStoreContent(AB_Store* self);
|
|
|
|
/* ````` closing store INSTANCE ````` */
|
|
|
|
AB_PUBLIC_API(void) /* abstore.cpp */
|
|
AB_Store_CloseObject(AB_Store* self, AB_Env* ev);
|
|
|
|
/* ````` store refcounting ````` */
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abstore.cpp */
|
|
AB_Store_Acquire(AB_Store* self, AB_Env* ev);
|
|
|
|
AB_PUBLIC_API(ab_ref_count) /* abstore.cpp */
|
|
AB_Store_Release(AB_Store* self, AB_Env* ev);
|
|
|
|
/* ````` accessing top store table (with or without acquire) ````` */
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abstore.cpp */
|
|
AB_Store_GetTopStoreTable(AB_Store* self, AB_Env* ev);
|
|
|
|
AB_PUBLIC_API(AB_Table*) /* abstore.cpp */
|
|
AB_Store_AcquireTopStoreTable(AB_Store* self, AB_Env* ev);
|
|
|
|
|
|
/* `````` `````` protos `````` `````` */
|
|
AB_END_C_PROTOS
|
|
/* `````` `````` protos `````` `````` */
|
|
|
|
|
|
#endif /* _ABTABLE_ */
|