Keychain/SecCFTypes.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18 //
  19 // SecCFTypes.h - CF runtime interface
  20 //
  21 #ifndef _SECURITY_SECCFTYPES_H_
  22 #define _SECURITY_SECCFTYPES_H_
  23
  24 #include <CoreFoundation/CFRuntime.h>
  25 #include <Security/globalizer.h>
  26
  27 namespace Security
  28 {
  29
  30 namespace KeychainCore
  31 {
  32
  33 class CFClass : protected CFRuntimeClass
  34 {
  35 public:
  36     CFClass(const char *name);
  37
  38 private:
  39     static Boolean equalType(CFTypeRef cf1, CFTypeRef cf2);
  40     static CFHashCode hashType(CFTypeRef cf);
  41         static CFStringRef copyFormattingDescType(CFTypeRef cf, CFDictionaryRef dict);
  42         static CFStringRef copyDebugDescType(CFTypeRef cf);
  43
  44         // CFAllocatorContext callbacks.
  45         static void *allocatorAllocate(CFIndex allocSize, CFOptionFlags hint, void *info);
  46         static void *allocatorReallocate(void *ptr, CFIndex newsize, CFOptionFlags hint, void *info);
  47         static void allocatorDeallocate(void *ptr, void *info);
  48         static CFIndex allocatorPreferredSize(CFIndex size, CFOptionFlags hint, void *info);
  49
  50 public:
  51     CFTypeID typeID;
  52         static CFAllocatorContext allocatorContext;
  53 };
  54
  55 /* Singleton that registers all the CFClass instances with the CFRuntime.
  56
  57    To make something a CFTypeRef you need to make the actual object inheirit from SecCFObject and provide implementation of the virtual functions in that class.
  58
  59    In addition to that you need to define an opque type for the C API like:
  60    typedef struct __OpaqueYourObject *YourObjectRef;
  61
  62    Add an instance of CFClass to the public section of SecCFTypes below to get it registered with the CFRuntime.
  63    CFClass yourObject;
  64
  65    XXX
  66    In your C++ code you should use SecPointer<YourObject> to refer to instances of your class.  SecPointers are just like autopointers and implement * and -> semantics.  They refcount the underlying object.  So to create an instance or your new object you would do something like:
  67
  68        SecPointer<YourObject> instance(new YourObject());
  69
  70    SecPointers have copy semantics and if you subclass SecPointer and define a operator < on the subclass you can even safely store instances of your class in stl containers.
  71
  72         Use then like this:
  73                 instance->somemethod();
  74         or if you want a reference to the underlying object:
  75                 YourObject &object = *instance;
  76         if you want a pointer to the underlying object:
  77                 YourObject *object = instance.get();
  78
  79         In the API glue you will need to use:
  80                 SecPointer<YourObject> instance;
  81                 [...] get the instance somehow
  82                 return instance->handle();
  83                 to return an opaque handle (the is a CFTypeRef) to your object.
  84
  85         when you obtain an object as input use:
  86                 SecYourObjectRef ref;
  87                 SecPointer<YourObject> instance = YourObject::required(ref);
  88                 to get a SecPointer to an instance of your object from the external CFTypeRef.
  89 */
  90 class SecCFTypes
  91 {
  92 public:
  93     SecCFTypes();
  94
  95 public:
  96         /* Add new instances of CFClass here that you want registered with the CF runtime. */
  97         CFClass Access;
  98         CFClass ACL;
  99         CFClass Certificate;
 100         CFClass CertificateRequest;
 101         CFClass Identity;
 102         CFClass IdentityCursor;
 103         CFClass ItemImpl;
 104         CFClass KCCursorImpl;
 105         CFClass KeychainImpl;
 106         CFClass KeyItem;
 107         CFClass Policy;
 108         CFClass PolicyCursor;
 109         CFClass Trust;
 110         CFClass TrustedApplication;
 111
 112         CFAllocatorRef allocator;
 113 };
 114
 115 extern SecCFTypes &gTypes();
 116
 117 } // end namespace KeychainCore
 118
 119 } // end namespace Security
 120
 121
 122 #endif // !_SECURITY_SECCFTYPES_H_