/* File: NameRegistry.h Contains: NameRegistry Interfaces Version: QuickTime 7.3 Copyright: (c) 2007 (c) 1993-2001 by Apple Computer, Inc., all rights reserved. Bugs?: For bug reports, consult the following page on the World Wide Web: http://developer.apple.com/bugreporter/ */ #ifndef __NAMEREGISTRY__ #define __NAMEREGISTRY__ #ifndef __MACTYPES__ #include #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 /******************************************************************************* * * Foundation Types * */ /* Value of a property */ typedef void * RegPropertyValue; /* Length of property value */ typedef UInt32 RegPropertyValueSize; /******************************************************************************* * * RegEntryID : The Global x-Namespace Entry Identifier * */ struct RegEntryID { UInt32 contents[4]; }; typedef struct RegEntryID RegEntryID; typedef RegEntryID * RegEntryIDPtr; /******************************************************************************* * * Root Entry Name Definitions (Applies to all Names in the RootNameSpace) * * o Names are a colon-separated list of name components. Name components * may not themselves contain colons. * o Names are presented as null-terminated ASCII character strings. * o Names follow similar parsing rules to Apple file system absolute * and relative paths. However the '::' parent directory syntax is * not currently supported. */ /* Max length of Entry Name */ enum { kRegCStrMaxEntryNameLength = 47 }; /* Entry Names are single byte ASCII */ typedef char RegCStrEntryName; typedef char * RegCStrEntryNamePtr; /* length of RegCStrEntryNameBuf = kRegCStrMaxEntryNameLength+1*/ typedef char RegCStrEntryNameBuf[48]; typedef char RegCStrPathName; typedef UInt32 RegPathNameSize; enum { kRegPathNameSeparator = ':', /* 0x3A */ kRegEntryNameTerminator = 0x00, /* '\0' */ kRegPathNameTerminator = 0x00 /* '\0' */ }; /******************************************************************************* * * Property Name and ID Definitions * (Applies to all Properties Regardless of NameSpace) */ enum { kRegMaximumPropertyNameLength = 31, /* Max length of Property Name */ kRegPropertyNameTerminator = 0x00 /* '\0' */ }; typedef char RegPropertyNameBuf[32]; typedef char RegPropertyName; typedef char * RegPropertyNamePtr; /******************************************************************************* * * Iteration Operations * * These specify direction when traversing the name relationships */ typedef UInt32 RegIterationOp; typedef RegIterationOp RegEntryIterationOp; enum { /* Absolute locations*/ kRegIterRoot = 0x00000002, /* "Upward" Relationships */ kRegIterParents = 0x00000003, /* include all parent(s) of entry */ /* "Downward" Relationships*/ kRegIterChildren = 0x00000004, /* include all children */ kRegIterSubTrees = 0x00000005, /* include all sub trees of entry */ kRegIterDescendants = 0x00000005, /* include all descendants of entry */ /* "Horizontal" Relationships */ kRegIterSibling = 0x00000006, /* include all siblings */ /* Keep doing the same thing*/ kRegIterContinue = 0x00000001 }; /******************************************************************************* * * Name Entry and Property Modifiers * * * * Modifiers describe special characteristics of names * and properties. Modifiers might be supported for * some names and not others. * * Device Drivers should not rely on functionality * specified as a modifier. */ typedef UInt32 RegModifiers; typedef RegModifiers RegEntryModifiers; typedef RegModifiers RegPropertyModifiers; enum { kRegNoModifiers = 0x00000000, /* no entry modifiers in place */ kRegUniversalModifierMask = 0x0000FFFF, /* mods to all entries */ kRegNameSpaceModifierMask = 0x00FF0000, /* mods to all entries within namespace */ kRegModifierMask = (long)0xFF000000 /* mods to just this entry */ }; /* Universal Property Modifiers */ enum { kRegPropertyValueIsSavedToNVRAM = 0x00000020, /* property is non-volatile (saved in NVRAM) */ kRegPropertyValueIsSavedToDisk = 0x00000040 /* property is non-volatile (saved on disk) */ }; /* NameRegistry version, Gestalt/PEF-style -- MUST BE KEPT IN SYNC WITH MAKEFILE !! */ enum { LatestNR_PEFVersion = 0x01030000 /* latest NameRegistryLib version (Gestalt/PEF-style) */ }; /* /////////////////////// // // The Registry API // /////////////////////// */ /* NameRegistry dispatch indexes */ enum { kSelectRegistryEntryIDInit = 0, kSelectRegistryEntryIDCompare = 1, kSelectRegistryEntryIDCopy = 2, kSelectRegistryEntryIDDispose = 3, kSelectRegistryCStrEntryCreate = 4, kSelectRegistryEntryDelete = 5, kSelectRegistryEntryCopy = 6, kSelectRegistryEntryIterateCreate = 7, kSelectRegistryEntryIterateDispose = 8, kSelectRegistryEntryIterateSet = 9, kSelectRegistryEntryIterate = 10, kSelectRegistryEntrySearch = 11, kSelectRegistryCStrEntryLookup = 12, kSelectRegistryEntryToPathSize = 13, kSelectRegistryCStrEntryToPath = 14, kSelectRegistryCStrEntryToName = 15, kSelectRegistryPropertyCreate = 16, kSelectRegistryPropertyDelete = 17, kSelectRegistryPropertyRename = 18, kSelectRegistryPropertyIterateCreate = 19, kSelectRegistryPropertyIterateDispose = 20, kSelectRegistryPropertyIterate = 21, kSelectRegistryPropertyGetSize = 22, kSelectRegistryPropertyGet = 23, kSelectRegistryPropertySet = 24, kSelectRegistryEntryGetMod = 25, kSelectRegistryEntrySetMod = 26, kSelectRegistryPropertyGetMod = 27, kSelectRegistryPropertySetMod = 28, kSelectRegistryEntryMod = 29, kSelectRegistryEntryPropertyMod = 30, /* if you add more selectors here, remember to change 'kSelectRegistryHighestSelector' below*/ kSelectRegistryHighestSelector = kSelectRegistryEntryPropertyMod }; /* /////////////////////// // // Entry Management // /////////////////////// */ /*------------------------------- * EntryID handling */ /* * Initialize an EntryID to a known invalid state * note: invalid != uninitialized */ #if CALL_NOT_IN_CARBON /* * RegistryEntryIDInit() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryIDInit(RegEntryID * id) TWOWORDINLINE(0x7000, 0xABE9); /* * Compare EntryID's for equality or if invalid * * If a NULL value is given for either id1 or id2, the other id * is compared with an invalid ID. If both are NULL, the id's * are consided equal (result = true). */ /* * RegistryEntryIDCompare() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( Boolean ) RegistryEntryIDCompare( const RegEntryID * id1, const RegEntryID * id2) TWOWORDINLINE(0x7001, 0xABE9); /* * Copy an EntryID */ /* * RegistryEntryIDCopy() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryIDCopy( const RegEntryID * src, RegEntryID * dst) TWOWORDINLINE(0x7002, 0xABE9); /* * Free an ID so it can be reused. */ /* * RegistryEntryIDDispose() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryIDDispose(RegEntryID * id) TWOWORDINLINE(0x7003, 0xABE9); /*------------------------------- * Adding and removing entries * * If (parentEntry) is NULL, the name is assumed * to be a rooted path. It is rooted to an anonymous, unnamed root. */ /* * RegistryCStrEntryCreate() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryCStrEntryCreate( const RegEntryID * parentEntry, const RegCStrPathName * name, RegEntryID * newEntry) TWOWORDINLINE(0x7004, 0xABE9); /* * RegistryEntryDelete() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryDelete(const RegEntryID * id) TWOWORDINLINE(0x7005, 0xABE9); /* * RegistryEntryCopy() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryCopy( RegEntryID * parentEntryID, RegEntryID * sourceDevice, RegEntryID * destDevice) TWOWORDINLINE(0x7006, 0xABE9); /*--------------------------- * Traversing the namespace * * To support arbitrary namespace implementations in the future, * I have hidden the form that the place pointer takes. The previous * interface exposed the place pointer by specifying it as a * RegEntryID. * * I have also removed any notion of returning the entries * in a particular order, because an implementation might * return the names in semi-random order. Many name service * implementations will store the names in a hashed lookup * table. * * Writing code to traverse some set of names consists of * a call to begin the iteration, the iteration loop, and * a call to end the iteration. The begin call initializes * the iteration cookie data structure. The call to end the * iteration should be called even in the case of error so * that allocated data structures can be freed. * * Create(...) * do { * Iterate(...); * } while (!done); * Dispose(...); * * This is the basic code structure for callers of the iteration * interface. */ #endif /* CALL_NOT_IN_CARBON */ typedef struct OpaqueRegEntryIter* RegEntryIter; /* * create/dispose the iterator structure * defaults to root with relationship = kRegIterDescendants */ #if CALL_NOT_IN_CARBON /* * RegistryEntryIterateCreate() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryIterateCreate(RegEntryIter * cookie) TWOWORDINLINE(0x7007, 0xABE9); /* * RegistryEntryIterateDispose() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryIterateDispose(RegEntryIter * cookie) TWOWORDINLINE(0x7008, 0xABE9); /* * set Entry Iterator to specified entry */ /* * RegistryEntryIterateSet() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryIterateSet( RegEntryIter * cookie, const RegEntryID * startEntryID) TWOWORDINLINE(0x7009, 0xABE9); /* * Return each value of the iteration * * return entries related to the current entry * with the specified relationship */ /* * RegistryEntryIterate() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryIterate( RegEntryIter * cookie, RegEntryIterationOp relationship, RegEntryID * foundEntry, Boolean * done) TWOWORDINLINE(0x700A, 0xABE9); /* * return entries with the specified property * * A NULL RegPropertyValue pointer will return an * entry with the property containing any value. */ /* * RegistryEntrySearch() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntrySearch( RegEntryIter * cookie, RegEntryIterationOp relationship, RegEntryID * foundEntry, Boolean * done, const RegPropertyName * propertyName, const void * propertyValue, RegPropertyValueSize propertySize) TWOWORDINLINE(0x700B, 0xABE9); /*-------------------------------- * Find a name in the namespace * * This is the fast lookup mechanism. * NOTE: A reverse lookup mechanism * has not been provided because * some name services may not * provide a fast, general reverse * lookup. */ /* * RegistryCStrEntryLookup() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryCStrEntryLookup( const RegEntryID * searchPointID, const RegCStrPathName * pathName, RegEntryID * foundEntry) TWOWORDINLINE(0x700C, 0xABE9); /*--------------------------------------------- * Convert an entry to a rooted name string * * A utility routine to turn an Entry ID * back into a name string. */ /* * RegistryEntryToPathSize() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryToPathSize( const RegEntryID * entryID, RegPathNameSize * pathSize) TWOWORDINLINE(0x700D, 0xABE9); /* * RegistryCStrEntryToPath() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryCStrEntryToPath( const RegEntryID * entryID, RegCStrPathName * pathName, RegPathNameSize pathSize) TWOWORDINLINE(0x700E, 0xABE9); /* * Parse a path name. * * Retrieve the last component of the path, and * return a spec for the parent. */ /* * RegistryCStrEntryToName() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryCStrEntryToName( const RegEntryID * entryID, RegEntryID * parentEntry, RegCStrEntryName * nameComponent, Boolean * done) TWOWORDINLINE(0x700F, 0xABE9); /* ////////////////////////////////////////////////////// // // Property Management // ////////////////////////////////////////////////////// */ /*------------------------------- * Adding and removing properties */ /* * RegistryPropertyCreate() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertyCreate( const RegEntryID * entryID, const RegPropertyName * propertyName, const void * propertyValue, RegPropertyValueSize propertySize) TWOWORDINLINE(0x7010, 0xABE9); /* * RegistryPropertyDelete() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertyDelete( const RegEntryID * entryID, const RegPropertyName * propertyName) TWOWORDINLINE(0x7011, 0xABE9); /* * RegistryPropertyRename() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertyRename( const RegEntryID * entry, const RegPropertyName * oldName, const RegPropertyName * newName) TWOWORDINLINE(0x7012, 0xABE9); /*--------------------------- * Traversing the Properties of a name * */ #endif /* CALL_NOT_IN_CARBON */ typedef struct OpaqueRegPropertyIter* RegPropertyIter; #if CALL_NOT_IN_CARBON /* * RegistryPropertyIterateCreate() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertyIterateCreate( const RegEntryID * entry, RegPropertyIter * cookie) TWOWORDINLINE(0x7013, 0xABE9); /* * RegistryPropertyIterateDispose() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertyIterateDispose(RegPropertyIter * cookie) TWOWORDINLINE(0x7014, 0xABE9); /* * RegistryPropertyIterate() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertyIterate( RegPropertyIter * cookie, RegPropertyName * foundProperty, Boolean * done) TWOWORDINLINE(0x7015, 0xABE9); /* * Get the value of the specified property for the specified entry. * */ /* * RegistryPropertyGetSize() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertyGetSize( const RegEntryID * entryID, const RegPropertyName * propertyName, RegPropertyValueSize * propertySize) TWOWORDINLINE(0x7016, 0xABE9); /* * (*propertySize) is the maximum size of the value returned in the buffer * pointed to by (propertyValue). Upon return, (*propertySize) is the size of the * value returned. */ /* * RegistryPropertyGet() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertyGet( const RegEntryID * entryID, const RegPropertyName * propertyName, void * propertyValue, RegPropertyValueSize * propertySize) TWOWORDINLINE(0x7017, 0xABE9); /* * RegistryPropertySet() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertySet( const RegEntryID * entryID, const RegPropertyName * propertyName, const void * propertyValue, RegPropertyValueSize propertySize) TWOWORDINLINE(0x7018, 0xABE9); /* ////////////////////////////////////////////////////// // // Modifier Management // ////////////////////////////////////////////////////// */ /* * Modifiers describe special characteristics of names * and properties. Modifiers might be supported for * some names and not others. * * Device Drivers should not rely on functionality * specified as a modifier. These interfaces * are for use in writing Experts. */ /* * Get and Set operators for entry modifiers */ /* * RegistryEntryGetMod() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryGetMod( const RegEntryID * entry, RegEntryModifiers * modifiers) TWOWORDINLINE(0x7019, 0xABE9); /* * RegistryEntrySetMod() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntrySetMod( const RegEntryID * entry, RegEntryModifiers modifiers) TWOWORDINLINE(0x701A, 0xABE9); /* * Get and Set operators for property modifiers */ /* * RegistryPropertyGetMod() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertyGetMod( const RegEntryID * entry, const RegPropertyName * name, RegPropertyModifiers * modifiers) TWOWORDINLINE(0x701B, 0xABE9); /* * RegistryPropertySetMod() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryPropertySetMod( const RegEntryID * entry, const RegPropertyName * name, RegPropertyModifiers modifiers) TWOWORDINLINE(0x701C, 0xABE9); /* * Iterator operator for entry modifier search */ /* * RegistryEntryMod() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryMod( RegEntryIter * cookie, RegEntryIterationOp relationship, RegEntryID * foundEntry, Boolean * done, RegEntryModifiers matchingModifiers) TWOWORDINLINE(0x701D, 0xABE9); /* * Iterator operator for entries with matching * property modifiers */ /* * RegistryEntryPropertyMod() * * Availability: * Non-Carbon CFM: in NameRegistryLib 1.0 and later * CarbonLib: not available * Mac OS X: not available */ EXTERN_API_C( OSStatus ) RegistryEntryPropertyMod( RegEntryIter * cookie, RegEntryIterationOp relationship, RegEntryID * foundEntry, Boolean * done, RegPropertyModifiers matchingModifiers) TWOWORDINLINE(0x701E, 0xABE9); #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 /* __NAMEREGISTRY__ */