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 void finalizeType(CFTypeRef cf);
  40     static Boolean equalType(CFTypeRef cf1, CFTypeRef cf2);
  41     static CFHashCode hashType(CFTypeRef cf);
  42         static CFStringRef copyFormattingDescType(CFTypeRef cf, CFDictionaryRef dict);
  43         static CFStringRef copyDebugDescType(CFTypeRef cf);
  44
  45 public:
  46     CFTypeID typeID;
  47 };
  48
  49 /* Singleton that registers all the CFClass instances with the CFRuntime.
  50
  51    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.
  52
  53    In addition to that you need to define an opque type for the C API like:
  54    typedef struct __OpaqueYourObject *YourObjectRef;
  55
  56    Add an instance of CFClass to the public section of SecCFTypes below to get it registered with the CFRuntime.
  57    CFClass yourObject;
  58
  59    XXX
  60    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:
  61
  62        SecPointer<YourObject> instance(new YourObject());
  63
  64    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.
  65
  66         Use then like this:
  67                 instance->somemethod();
  68         or if you want a reference to the underlying object:
  69                 YourObject &object = *instance;
  70         if you want a pointer to the underlying object:
  71                 YourObject *object = instance.get();
  72
  73         In the API glue you will need to use:
  74                 SecPointer<YourObject> instance;
  75                 [...] get the instance somehow
  76                 return instance->handle();
  77                 to return an opaque handle (the is a CFTypeRef) to your object.
  78
  79         when you obtain an object as input use:
  80                 SecYourObjectRef ref;
  81                 SecPointer<YourObject> instance = YourObject::required(ref);
  82                 to get a SecPointer to an instance of your object from the external CFTypeRef.
  83 */
  84 class SecCFTypes
  85 {
  86 public:
  87     SecCFTypes();
  88
  89 public:
  90         /* Add new instances of CFClass here that you want registered with the CF runtime. */
  91         CFClass Access;
  92         CFClass ACL;
  93         CFClass Certificate;
  94         CFClass CertificateRequest;
  95         CFClass Identity;
  96         CFClass IdentityCursor;
  97         CFClass ItemImpl;
  98         CFClass KCCursorImpl;
  99         CFClass KeychainImpl;
 100         CFClass KeyItem;
 101         CFClass Policy;
 102         CFClass PolicyCursor;
 103         CFClass Trust;
 104         CFClass TrustedApplication;
 105 };
 106
 107 extern SecCFTypes &gTypes();
 108
 109 } // end namespace KeychainCore
 110
 111 } // end namespace Security
 112
 113
 114 #endif // !_SECURITY_SECCFTYPES_H_