libsecurity_keychain/lib/SecCFTypes.h

   1 /*
   2  * Copyright (c) 2002-2004 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 //
  25 // SecCFTypes.h - CF runtime interface
  26 //
  27 #ifndef _SECURITY_SECCFTYPES_H_
  28 #define _SECURITY_SECCFTYPES_H_
  29
  30 #include <CoreFoundation/CFRuntime.h>
  31 #include <security_utilities/globalizer.h>
  32 #include <security_utilities/cfclass.h>
  33
  34 namespace Security
  35 {
  36
  37 namespace KeychainCore
  38 {
  39
  40 /* Singleton that registers all the CFClass instances with the CFRuntime.
  41
  42    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.
  43
  44    In addition to that you need to define an opque type for the C API like:
  45    typedef struct __OpaqueYourObject *YourObjectRef;
  46
  47    Add an instance of CFClass to the public section of SecCFTypes below to get it registered with the CFRuntime.
  48    CFClass yourObject;
  49
  50    XXX
  51    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:
  52
  53        SecPointer<YourObject> instance(new YourObject());
  54
  55    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.
  56
  57         Use then like this:
  58                 instance->somemethod();
  59         or if you want a reference to the underlying object:
  60                 YourObject &object = *instance;
  61         if you want a pointer to the underlying object:
  62                 YourObject *object = instance.get();
  63
  64         In the API glue you will need to use:
  65                 SecPointer<YourObject> instance;
  66                 [...] get the instance somehow
  67                 return instance->handle();
  68                 to return an opaque handle (the is a CFTypeRef) to your object.
  69
  70         when you obtain an object as input use:
  71                 SecYourObjectRef ref;
  72                 SecPointer<YourObject> instance = YourObject::required(ref);
  73                 to get a SecPointer to an instance of your object from the external CFTypeRef.
  74 */
  75 class SecCFTypes
  76 {
  77 public:
  78     SecCFTypes();
  79
  80 public:
  81         /* Add new instances of CFClass here that you want registered with the CF runtime. */
  82         CFClass Access;
  83         CFClass ACL;
  84         CFClass Certificate;
  85         CFClass CertificateRequest;
  86         CFClass Identity;
  87         CFClass IdentityCursor;
  88         CFClass ItemImpl;
  89         CFClass KCCursorImpl;
  90         CFClass KeychainImpl;
  91         CFClass KeyItem;
  92     CFClass PasswordImpl;
  93         CFClass Policy;
  94         CFClass PolicyCursor;
  95         CFClass Trust;
  96         CFClass TrustedApplication;
  97         CFClass ExtendedAttribute;
  98 };
  99
 100 extern SecCFTypes &gTypes();
 101
 102 } // end namespace KeychainCore
 103
 104 } // end namespace Security
 105
 106
 107 #endif // !_SECURITY_SECCFTYPES_H_