Dictionary.h

Go to the documentation of this file.

 
#ifndef __DICTIONARY__
#define __DICTIONARY__
 
#ifndef __MACTYPES__
#include <MacTypes.h>
#endif
 
#ifndef __FILES__
#include <Files.h>
#endif
 
#ifndef __AEREGISTRY__
#include <AERegistry.h>
#endif
 
#ifndef __CODEFRAGMENTS__
#include <CodeFragments.h>
#endif
 
#ifndef __MACERRORS__
#include <MacErrors.h>
#endif
 
#if PRAGMA_ONCE
#pragma once
#endif
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#if PRAGMA_IMPORT
#pragma import on
#endif
 
#if PRAGMA_STRUCT_ALIGN
#pragma options align = power
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(push, 2)
#elif PRAGMA_STRUCT_PACK
#pragma pack(2)
#endif
 
    enum
    {
        kDictionaryFileType = FOUR_CHAR_CODE('dict'),
        kDCMDictionaryHeaderSignature = FOUR_CHAR_CODE('dict'),
        kDCMDictionaryHeaderVersion = 2
    };
 
    enum
    {
        kDCMAnyFieldTag = typeWildCard,
        kDCMAnyFieldType = typeWildCard
    };
 
    enum
    {
        keyDCMFieldTag = FOUR_CHAR_CODE('ftag'),      /* typeEnumeration */
        keyDCMFieldType = FOUR_CHAR_CODE('ftyp'),     /* typeEnumeration */
        keyDCMMaxRecordSize = FOUR_CHAR_CODE('mrsz'), /* typeMagnitude */
        keyDCMFieldAttributes = FOUR_CHAR_CODE('fatr'),
        keyDCMFieldDefaultData = FOUR_CHAR_CODE('fdef'),
        keyDCMFieldName = FOUR_CHAR_CODE('fnam'), /* typeChar */
        keyDCMFieldFindMethods =
            FOUR_CHAR_CODE('ffnd') /* typeAEList of typeDCMFindMethod */
    };
 
    enum
    {
        typeDCMFieldAttributes = FOUR_CHAR_CODE('fatr'),
        typeDCMFindMethod = FOUR_CHAR_CODE('fmth')
    };
 
    enum
    {
        kDCMIndexedFieldMask = 0x00000001,
        kDCMRequiredFieldMask = 0x00000002,
        kDCMIdentifyFieldMask = 0x00000004,
        kDCMFixedSizeFieldMask = 0x00000008,
        kDCMHiddenFieldMask = (long)0x80000000
    };
 
    typedef OptionBits DCMFieldAttributes;
    enum
    {
        pDCMAccessMethod = FOUR_CHAR_CODE('amtd'), /* data type: typeChar ReadOnly */
        pDCMPermission = FOUR_CHAR_CODE('perm'),   /* data type: typeUInt16 */
        pDCMListing = FOUR_CHAR_CODE('list'),      /* data type: typeUInt16 */
        pDCMMaintenance = FOUR_CHAR_CODE('mtnc'),  /* data type: typeUInt16 */
        pDCMLocale = FOUR_CHAR_CODE('locl'),       /* data type: typeUInt32.  Optional;
                                                      default = kLocaleIdentifierWildCard */
        pDCMClass = pClass,                        /* data type: typeUInt16 */
        pDCMCopyright = FOUR_CHAR_CODE('info')     /* data type: typeChar */
    };
 
    enum
    {
        kDCMReadOnlyDictionary = 0,
        kDCMReadWriteDictionary = 1
    };
 
    enum
    {
        kDCMAllowListing = 0,
        kDCMProhibitListing = 1
    };
 
    enum
    {
        kDCMUserDictionaryClass = 0,
        kDCMSpecificDictionaryClass = 1,
        kDCMBasicDictionaryClass = 2
    };
 
    enum
    {
        kDCMFindMethodExactMatch = kAEEquals,
        kDCMFindMethodBeginningMatch = kAEBeginsWith,
        kDCMFindMethodContainsMatch = kAEContains,
        kDCMFindMethodEndingMatch = kAEEndsWith,
        kDCMFindMethodForwardTrie =
            FOUR_CHAR_CODE('ftri'), /* used for morphological analysis*/
        kDCMFindMethodBackwardTrie =
            FOUR_CHAR_CODE('btri') /* used for morphological analysis*/
    };
 
    typedef OSType DCMFindMethod;
    enum
    {
        kDCMCanUseFileDictionaryMask = 0x00000001,
        kDCMCanUseMemoryDictionaryMask = 0x00000002,
        kDCMCanStreamDictionaryMask = 0x00000004,
        kDCMCanHaveMultipleIndexMask = 0x00000008,
        kDCMCanModifyDictionaryMask = 0x00000010,
        kDCMCanCreateDictionaryMask = 0x00000020,
        kDCMCanAddDictionaryFieldMask = 0x00000040,
        kDCMCanUseTransactionMask = 0x00000080
    };
 
    typedef OptionBits DCMAccessMethodFeature;
    typedef UInt32 DCMUniqueID;
    typedef struct OpaqueDCMObjectID *DCMObjectID;
    typedef DCMObjectID DCMAccessMethodID;
    typedef DCMObjectID DCMDictionaryID;
#define kDCMInvalidObjectID ((DCMObjectID)kInvalidID)
    typedef struct OpaqueDCMObjectRef *DCMObjectRef;
    typedef DCMObjectRef DCMDictionaryRef;
    typedef DCMObjectRef DCMDictionaryStreamRef;
#define kDCMInvalidObjectRef ((DCMObjectRef)kInvalidID)
    typedef struct OpaqueDCMObjectIterator *DCMObjectIterator;
    typedef DCMObjectIterator DCMAccessMethodIterator;
    typedef DCMObjectIterator DCMDictionaryIterator;
    typedef struct OpaqueDCMFoundRecordIterator *DCMFoundRecordIterator;
    typedef DescType DCMFieldTag;
    typedef DescType DCMFieldType;
    struct DCMDictionaryHeader
    {
        FourCharCode headerSignature;
        UInt32 headerVersion;
        ByteCount headerSize;
        Str63 accessMethod;
    };
    typedef struct DCMDictionaryHeader DCMDictionaryHeader;
    typedef CALLBACK_API(Boolean,
                         DCMProgressFilterProcPtr)(Boolean determinateProcess,
                                                   UInt16 percentageComplete,
                                                   UInt32 callbackUD);
    typedef STACK_UPP_TYPE(DCMProgressFilterProcPtr) DCMProgressFilterUPP;
#if CALL_NOT_IN_CARBON
    DCMProgressFilterUPP
    NewDCMProgressFilterUPP(DCMProgressFilterProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
    enum
    {
        uppDCMProgressFilterProcInfo = 0x00000E50
    }; /* pascal 1_byte Func(1_byte, 2_bytes, 4_bytes) */
#ifdef __cplusplus
    inline DCMProgressFilterUPP
    NewDCMProgressFilterUPP(DCMProgressFilterProcPtr userRoutine)
    {
        return (DCMProgressFilterUPP)NewRoutineDescriptor(
            (ProcPtr)(userRoutine), uppDCMProgressFilterProcInfo,
            GetCurrentArchitecture());
    }
#else
#define NewDCMProgressFilterUPP(userRoutine)                                  \
    (DCMProgressFilterUPP) NewRoutineDescriptor((ProcPtr)(userRoutine),       \
                                                uppDCMProgressFilterProcInfo, \
                                                GetCurrentArchitecture())
#endif
#endif
 
    void
    DisposeDCMProgressFilterUPP(DCMProgressFilterUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
    inline void DisposeDCMProgressFilterUPP(DCMProgressFilterUPP userUPP)
    {
        DisposeRoutineDescriptor((UniversalProcPtr)userUPP);
    }
#else
#define DisposeDCMProgressFilterUPP(userUPP) DisposeRoutineDescriptor(userUPP)
#endif
#endif
 
    Boolean
    InvokeDCMProgressFilterUPP(Boolean determinateProcess,
                               UInt16 percentageComplete, UInt32 callbackUD,
                               DCMProgressFilterUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
    inline Boolean InvokeDCMProgressFilterUPP(Boolean determinateProcess,
                                              UInt16 percentageComplete,
                                              UInt32 callbackUD,
                                              DCMProgressFilterUPP userUPP)
    {
        return (Boolean)CALL_THREE_PARAMETER_UPP(
            userUPP, uppDCMProgressFilterProcInfo, determinateProcess,
            percentageComplete, callbackUD);
    }
#else
#define InvokeDCMProgressFilterUPP(determinateProcess, percentageComplete,      \
                                   callbackUD, userUPP)                         \
    (Boolean) CALL_THREE_PARAMETER_UPP((userUPP), uppDCMProgressFilterProcInfo, \
                                       (determinateProcess),                    \
                                       (percentageComplete), (callbackUD))
#endif
#endif
 
#endif /* CALL_NOT_IN_CARBON */
 
#if CALL_NOT_IN_CARBON || OLDROUTINENAMES
/* support for pre-Carbon UPP routines: New...Proc and Call...Proc */
#define NewDCMProgressFilterProc(userRoutine) \
    NewDCMProgressFilterUPP(userRoutine)
#define CallDCMProgressFilterProc(userRoutine, determinateProcess,     \
                                  percentageComplete, callbackUD)      \
    InvokeDCMProgressFilterUPP(determinateProcess, percentageComplete, \
                               callbackUD, userRoutine)
#endif /* CALL_NOT_IN_CARBON */
 
    UInt32
    DCMLibraryVersion(void);
 
    OSStatus
    DCMNewDictionary(DCMAccessMethodID accessMethodID,
                     const FSSpec *newDictionaryFile, ScriptCode scriptTag,
                     const AEDesc *listOfFieldInfoRecords, Boolean invisible,
                     ItemCount recordCapacity, DCMDictionaryID *newDictionary);
 
    OSStatus
    DCMDeriveNewDictionary(DCMDictionaryID srcDictionary,
                           const FSSpec *newDictionaryFile, ScriptCode scriptTag,
                           Boolean invisible, ItemCount recordCapacity,
                           DCMDictionaryID *newDictionary);
 
    OSStatus
    DCMDeleteDictionary(DCMDictionaryID dictionaryID);
 
    OSStatus
    DCMRegisterDictionaryFile(const FSSpec *dictionaryFile,
                              DCMDictionaryID *dictionaryID);
 
    OSStatus
    DCMUnregisterDictionary(DCMDictionaryID dictionaryID);
 
    OSStatus
    DCMOpenDictionary(DCMDictionaryID dictionaryID, ByteCount protectKeySize,
                      ConstLogicalAddress protectKey,
                      DCMDictionaryRef *dictionaryRef);
 
    OSStatus
    DCMCloseDictionary(DCMDictionaryRef dictionaryRef);
 
    OSStatus
    DCMGetDictionaryWriteAccess(DCMDictionaryRef dictionaryRef,
                                Duration timeOutDuration);
 
    OSStatus
    DCMReleaseDictionaryWriteAccess(DCMDictionaryRef dictionaryRef,
                                    Boolean commitTransaction);
 
    OSStatus
    DCMFindRecords(DCMDictionaryRef dictionaryRef, DCMFieldTag keyFieldTag,
                   ByteCount keySize, ConstLogicalAddress keyData,
                   DCMFindMethod findMethod, ItemCount preFetchedDataNum,
                   DCMFieldTag preFetchedData[], ItemCount skipCount,
                   ItemCount maxRecordCount,
                   DCMFoundRecordIterator *recordIterator);
 
    ItemCount
    DCMCountRecordIterator(DCMFoundRecordIterator recordIterator);
 
    OSStatus
    DCMIterateFoundRecord(DCMFoundRecordIterator recordIterator,
                          ByteCount maxKeySize, ByteCount *actualKeySize,
                          LogicalAddress keyData, DCMUniqueID *uniqueID,
                          AEDesc *dataList);
 
    OSStatus
    DCMDisposeRecordIterator(DCMFoundRecordIterator recordIterator);
 
    OSStatus
    DCMCountRecord(DCMDictionaryID dictionaryID, ItemCount *count);
 
    OSStatus
    DCMGetRecordSequenceNumber(DCMDictionaryRef dictionaryRef,
                               DCMFieldTag keyFieldTag, ByteCount keySize,
                               ConstLogicalAddress keyData, DCMUniqueID uniqueID,
                               ItemCount *sequenceNum);
 
    OSStatus
    DCMGetNthRecord(DCMDictionaryRef dictionaryRef, DCMFieldTag keyFieldTag,
                    ItemCount serialNum, ByteCount maxKeySize, ByteCount *keySize,
                    LogicalAddress keyData, DCMUniqueID *uniqueID);
 
    OSStatus
    DCMGetNextRecord(DCMDictionaryRef dictionaryRef, DCMFieldTag keyFieldTag,
                     ByteCount keySize, ConstLogicalAddress keyData,
                     DCMUniqueID uniqueID, ByteCount maxKeySize,
                     ByteCount *nextKeySize, LogicalAddress nextKeyData,
                     DCMUniqueID *nextUniqueID);
 
    OSStatus
    DCMGetPrevRecord(DCMDictionaryRef dictionaryRef, DCMFieldTag keyFieldTag,
                     ByteCount keySize, ConstLogicalAddress keyData,
                     DCMUniqueID uniqueID, ByteCount maxKeySize,
                     ByteCount *prevKeySize, LogicalAddress prevKeyData,
                     DCMUniqueID *prevUniqueID);
 
    OSStatus
    DCMGetFieldData(DCMDictionaryRef dictionaryRef, DCMFieldTag keyFieldTag,
                    ByteCount keySize, ConstLogicalAddress keyData,
                    DCMUniqueID uniqueID, ItemCount numOfData,
                    const DCMFieldTag dataTag[], AEDesc *dataList);
 
    OSStatus
    DCMSetFieldData(DCMDictionaryRef dictionaryRef, DCMFieldTag keyFieldTag,
                    ByteCount keySize, ConstLogicalAddress keyData,
                    DCMUniqueID uniqueID, const AEDesc *dataList);
 
    OSStatus
    DCMAddRecord(DCMDictionaryRef dictionaryRef, DCMFieldTag keyFieldTag,
                 ByteCount keySize, ConstLogicalAddress keyData, Boolean checkOnly,
                 const AEDesc *dataList, DCMUniqueID *newUniqueID);
 
    OSStatus
    DCMDeleteRecord(DCMDictionaryRef dictionaryRef, DCMFieldTag keyFieldTag,
                    ByteCount keySize, ConstLogicalAddress keyData,
                    DCMUniqueID uniqueID);
 
    OSStatus
    DCMReorganizeDictionary(DCMDictionaryID dictionaryID, ItemCount extraCapacity,
                            DCMProgressFilterUPP progressProc, UInt32 userData);
 
    OSStatus
    DCMCompactDictionary(DCMDictionaryID dictionaryID,
                         DCMProgressFilterUPP progressProc, UInt32 userData);
 
    OSStatus
    DCMGetFileFromDictionaryID(DCMDictionaryID dictionaryID, FSSpec *fileRef);
 
    OSStatus
    DCMGetDictionaryIDFromFile(const FSSpec *fileRef,
                               DCMDictionaryID *dictionaryID);
 
    DCMDictionaryID
    DCMGetDictionaryIDFromRef(DCMDictionaryRef dictionaryRef);
 
    OSStatus
    DCMGetDictionaryFieldInfo(DCMDictionaryID dictionaryID, DCMFieldTag fieldTag,
                              AEDesc *fieldInfoRecord);
 
    OSStatus
    DCMGetDictionaryProperty(DCMDictionaryID dictionaryID, DCMFieldTag propertyTag,
                             ByteCount maxPropertySize, ByteCount *actualSize,
                             LogicalAddress propertyValue);
 
    OSStatus
    DCMSetDictionaryProperty(DCMDictionaryID dictionaryID, DCMFieldTag propertyTag,
                             ByteCount propertySize,
                             ConstLogicalAddress propertyValue);
 
    OSStatus
    DCMGetDictionaryPropertyList(DCMDictionaryID dictionaryID,
                                 ItemCount maxPropertyNum, ItemCount *numProperties,
                                 DCMFieldTag propertyTag[]);
 
    OSStatus
    DCMCreateDictionaryIterator(DCMDictionaryIterator *dictionaryIterator);
 
    OSStatus
    DCMCreateAccessMethodIterator(DCMAccessMethodIterator *accessMethodIterator);
 
    ItemCount
    DCMCountObjectIterator(DCMObjectIterator iterator);
 
    OSStatus
    DCMIterateObject(DCMObjectIterator iterator, DCMObjectID *objectID);
 
    OSStatus
    DCMResetObjectIterator(DCMObjectIterator iterator);
 
    OSStatus
    DCMDisposeObjectIterator(DCMObjectIterator iterator);
 
    OSStatus
    DCMGetAccessMethodIDFromName(ConstStr63Param accessMethodName,
                                 DCMAccessMethodID *accessMethodID);
 
    OSStatus
    DCMCreateFieldInfoRecord(DescType fieldTag, DescType fieldType,
                             ByteCount maxRecordSize,
                             DCMFieldAttributes fieldAttributes,
                             AEDesc *fieldDefaultData,
                             ItemCount numberOfFindMethods,
                             DCMFindMethod findMethods[], AEDesc *fieldInfoRecord);
 
    OSStatus
    DCMGetFieldTagAndType(const AEDesc *fieldInfoRecord, DCMFieldTag *fieldTag,
                          DCMFieldType *fieldType);
 
    OSStatus
    DCMGetFieldMaxRecordSize(const AEDesc *fieldInfoRecord,
                             ByteCount *maxRecordSize);
 
    OSStatus
    DCMGetFieldAttributes(const AEDesc *fieldInfoRecord,
                          DCMFieldAttributes *attributes);
 
    OSStatus
    DCMGetFieldDefaultData(const AEDesc *fieldInfoRecord, DescType desiredType,
                           AEDesc *fieldDefaultData);
 
    OSStatus
    DCMGetFieldFindMethods(const AEDesc *fieldInfoRecord,
                           ItemCount findMethodsArrayMaxSize,
                           DCMFindMethod findMethods[],
                           ItemCount *actualNumberOfFindMethods);
 
#if TARGET_RT_MAC_CFM
#ifdef __cplusplus
    inline pascal Boolean DCMDictionaryManagerAvailable()
    {
        return (DCMLibraryVersion != (void *)kUnresolvedCFragSymbolAddress);
    }
#else
#define DCMDictionaryManagerAvailable()     ((DCMLibraryVersion != (void*)kUnresolvedCFragSymbolAddress)
#endif
#elif TARGET_RT_MAC_MACHO
/* Dictionary Manager is always available on OS X */
#ifdef __cplusplus
inline pascal Boolean DCMDictionaryManagerAvailable() { return true; }
#else
#define DCMDictionaryManagerAvailable() (true)
#endif
#endif /*  */
 
#define kAppleJapaneseDefaultAccessMethodName \
    "\pDAM:Apple Backward Trie Access Method"
    enum
    {
        kMaxYomiLengthInAppleJapaneseDictionary = 40,
        kMaxKanjiLengthInAppleJapaneseDictionary = 64
    };
 
    enum
    {
        kDCMJapaneseYomiTag = FOUR_CHAR_CODE('yomi'),
        kDCMJapaneseHyokiTag = FOUR_CHAR_CODE('hyok'),
        kDCMJapaneseHinshiTag = FOUR_CHAR_CODE('hins'),
        kDCMJapaneseWeightTag = FOUR_CHAR_CODE('hind'),
        kDCMJapanesePhoneticTag = FOUR_CHAR_CODE('hton'),
        kDCMJapaneseAccentTag = FOUR_CHAR_CODE('acnt'),
        kDCMJapaneseOnKunReadingTag = FOUR_CHAR_CODE('OnKn'),
        kDCMJapaneseFukugouInfoTag = FOUR_CHAR_CODE('fuku')
    };
 
    enum
    {
        kDCMJapaneseYomiType = typeUnicodeText,
        kDCMJapaneseHyokiType = typeUnicodeText,
        kDCMJapaneseHinshiType = FOUR_CHAR_CODE('hins'),
        kDCMJapaneseWeightType = typeShortInteger,
        kDCMJapanesePhoneticType = typeUnicodeText,
        kDCMJapaneseAccentType = FOUR_CHAR_CODE('byte'),
        kDCMJapaneseOnKunReadingType = typeUnicodeText,
        kDCMJapaneseFukugouInfoType = FOUR_CHAR_CODE('fuku')
    };
 
#if PRAGMA_STRUCT_ALIGN
#pragma options align = reset
#pragma options align = mac68k
#endif
 
    enum
    {
        /* Dictionary data insertion modes */
        kInsert = 0,         /* Only insert the input entry if there is nothing in the
                                dictionary that matches the key. */
        kReplace = 1,        /* Only replace the entries which match the key with the input
                                entry. */
        kInsertOrReplace = 2 /* Insert the entry if there is nothing in the dictionary
                                which matches the key, otherwise replaces the existing
                                matched entries with the input entry. */
    };
 
    /* This Was InsertMode */
 
    typedef short DictionaryDataInsertMode;
    enum
    {
        /* Key attribute constants */
        kIsCaseSensitive = 0x10,          /* case sensitive = 16       */
        kIsNotDiacriticalSensitive = 0x20 /* diac not sensitive = 32    */
    };
 
    enum
    {
        /* Registered attribute type constants.   */
        kNoun = -1,
        kVerb = -2,
        kAdjective = -3,
        kAdverb = -4
    };
 
    /* This Was AttributeType */
    typedef SInt8 DictionaryEntryAttribute;
    /* Dictionary information record */
    struct DictionaryInformation
    {
        FSSpec dictionaryFSSpec;
        SInt32 numberOfRecords;
        SInt32 currentGarbageSize;
        ScriptCode script;
        SInt16 maximumKeyLength;
        SInt8 keyAttributes;
    };
    typedef struct DictionaryInformation DictionaryInformation;
    struct DictionaryAttributeTable
    {
        UInt8 datSize;
        DictionaryEntryAttribute datTable[1];
    };
    typedef struct DictionaryAttributeTable DictionaryAttributeTable;
    typedef DictionaryAttributeTable *DictionaryAttributeTablePtr;
#if CALL_NOT_IN_CARBON
    OSErr
    InitializeDictionary(const FSSpec *theFsspecPtr, SInt16 maximumKeyLength,
                         SInt8 keyAttributes, ScriptCode script);
 
    OSErr
    OpenDictionary(const FSSpec *theFsspecPtr, SInt8 accessPermission,
                   SInt32 *dictionaryReference);
 
    OSErr
    CloseDictionary(SInt32 dictionaryReference);
 
    OSErr
    InsertRecordToDictionary(SInt32 dictionaryReference, ConstStr255Param key,
                             Handle recordDataHandle,
                             DictionaryDataInsertMode whichMode);
 
    OSErr
    DeleteRecordFromDictionary(SInt32 dictionaryReference, ConstStr255Param key);
 
    OSErr
    FindRecordInDictionary(
        SInt32 dictionaryReference, ConstStr255Param key,
        DictionaryAttributeTablePtr requestedAttributeTablePointer,
        Handle recordDataHandle);
 
    OSErr
    FindRecordByIndexInDictionary(
        SInt32 dictionaryReference, SInt32 recordIndex,
        DictionaryAttributeTablePtr requestedAttributeTablePointer,
        Str255 recordKey, Handle recordDataHandle);
 
    OSErr
    GetDictionaryInformation(SInt32 dictionaryReference,
                             DictionaryInformation *theDictionaryInformation);
 
    OSErr
    CompactDictionary(SInt32 dictionaryReference);
 
#endif /* CALL_NOT_IN_CARBON */
 
#if PRAGMA_STRUCT_ALIGN
#pragma options align = reset
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(pop)
#elif PRAGMA_STRUCT_PACK
#pragma pack()
#endif
 
#ifdef PRAGMA_IMPORT_OFF
#pragma import off
#elif PRAGMA_IMPORT
#pragma import reset
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif /* __DICTIONARY__ */