runtime/objc.h

   1 /*
   2  * Copyright (c) 1999-2007 Apple 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  *      objc.h
  25  *      Copyright 1988-1996, NeXT Software, Inc.
  26  */
  27
  28 #ifndef _OBJC_OBJC_H_
  29 #define _OBJC_OBJC_H_
  30
  31 #include <sys/types.h>      // for __DARWIN_NULL
  32 #include <Availability.h>
  33 #include <objc/objc-api.h>
  34
  35 #if !OBJC_TYPES_DEFINED
  36 /// An opaque type that represents an Objective-C class.
  37 typedef struct objc_class *Class;
  38
  39 /// Represents an instance of a class.
  40 struct objc_object {
  41     Class isa  OBJC_ISA_AVAILABILITY;
  42 };
  43
  44 /// A pointer to an instance of a class.
  45 typedef struct objc_object *id;
  46 #endif
  47
  48 /// An opaque type that represents a method selector.
  49 typedef struct objc_selector *SEL;
  50
  51 /// A pointer to the function of a method implementation.
  52 #if !OBJC_OLD_DISPATCH_PROTOTYPES
  53 typedef void (*IMP)(void /* id, SEL, ... */ );
  54 #else
  55 typedef id (*IMP)(id, SEL, ...);
  56 #endif
  57
  58 #define OBJC_BOOL_DEFINED
  59
  60 /// Type to represent a boolean value.
  61 typedef signed char BOOL;
  62 // BOOL is explicitly signed so @encode(BOOL) == "c" rather than "C"
  63 // even if -funsigned-char is used.
  64
  65 #if __has_feature(objc_bool)
  66 #define YES             __objc_yes
  67 #define NO              __objc_no
  68 #else
  69 #define YES             ((BOOL)1)
  70 #define NO              ((BOOL)0)
  71 #endif
  72
  73 #ifndef Nil
  74 # if __has_feature(cxx_nullptr)
  75 #   define Nil nullptr
  76 # else
  77 #   define Nil __DARWIN_NULL
  78 # endif
  79 #endif
  80
  81 #ifndef nil
  82 # if __has_feature(cxx_nullptr)
  83 #   define nil nullptr
  84 # else
  85 #   define nil __DARWIN_NULL
  86 # endif
  87 #endif
  88
  89 #if ! (defined(__OBJC_GC__)  ||  __has_feature(objc_arc))
  90 #define __strong /* empty */
  91 #endif
  92
  93 #if !__has_feature(objc_arc)
  94 #define __unsafe_unretained /* empty */
  95 #define __autoreleasing /* empty */
  96 #endif
  97
  98
  99 /**
 100  * Returns the name of the method specified by a given selector.
 101  *
 102  * @param sel A pointer of type \c SEL. Pass the selector whose name you wish to determine.
 103  *
 104  * @return A C string indicating the name of the selector.
 105  */
 106 OBJC_EXPORT const char *sel_getName(SEL sel)
 107     __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
 108
 109 /**
 110  * Registers a method with the Objective-C runtime system, maps the method
 111  * name to a selector, and returns the selector value.
 112  *
 113  * @param str A pointer to a C string. Pass the name of the method you wish to register.
 114  *
 115  * @return A pointer of type SEL specifying the selector for the named method.
 116  *
 117  * @note You must register a method name with the Objective-C runtime system to obtain the
 118  *  method’s selector before you can add the method to a class definition. If the method name
 119  *  has already been registered, this function simply returns the selector.
 120  */
 121 OBJC_EXPORT SEL sel_registerName(const char *str)
 122     __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
 123
 124 /**
 125  * Returns the class name of a given object.
 126  *
 127  * @param obj An Objective-C object.
 128  *
 129  * @return The name of the class of which \e obj is an instance.
 130  */
 131 OBJC_EXPORT const char *object_getClassName(id obj)
 132     __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
 133
 134 /**
 135  * Returns a pointer to any extra bytes allocated with an instance given object.
 136  *
 137  * @param obj An Objective-C object.
 138  *
 139  * @return A pointer to any extra bytes allocated with \e obj. If \e obj was
 140  *   not allocated with any extra bytes, then dereferencing the returned pointer is undefined.
 141  *
 142  * @note This function returns a pointer to any extra bytes allocated with the instance
 143  *  (as specified by \c class_createInstance with extraBytes>0). This memory follows the
 144  *  object's ordinary ivars, but may not be adjacent to the last ivar.
 145  * @note The returned pointer is guaranteed to be pointer-size aligned, even if the area following
 146  *  the object's last ivar is less aligned than that. Alignment greater than pointer-size is never
 147  *  guaranteed, even if the area following the object's last ivar is more aligned than that.
 148  * @note In a garbage-collected environment, the memory is scanned conservatively.
 149  */
 150 OBJC_EXPORT void *object_getIndexedIvars(id obj)
 151     __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
 152
 153 /**
 154  * Identifies a selector as being valid or invalid.
 155  *
 156  * @param sel The selector you want to identify.
 157  *
 158  * @return YES if selector is valid and has a function implementation, NO otherwise.
 159  *
 160  * @warning On some platforms, an invalid reference (to invalid memory addresses) can cause
 161  *  a crash.
 162  */
 163 OBJC_EXPORT BOOL sel_isMapped(SEL sel)
 164     __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
 165
 166 /**
 167  * Registers a method name with the Objective-C runtime system.
 168  *
 169  * @param str A pointer to a C string. Pass the name of the method you wish to register.
 170  *
 171  * @return A pointer of type SEL specifying the selector for the named method.
 172  *
 173  * @note The implementation of this method is identical to the implementation of \c sel_registerName.
 174  * @note Prior to OS X version 10.0, this method tried to find the selector mapped to the given name
 175  *  and returned \c NULL if the selector was not found. This was changed for safety, because it was
 176  *  observed that many of the callers of this function did not check the return value for \c NULL.
 177  */
 178 OBJC_EXPORT SEL sel_getUid(const char *str)
 179     __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
 180
 181
 182 // Obsolete ARC conversions. Deprecation forthcoming.
 183 // Use CFBridgingRetain, CFBridgingRelease, and __bridge casts instead.
 184
 185 typedef const void* objc_objectptr_t;
 186
 187 #if __has_feature(objc_arc)
 188 #   define objc_retainedObject(o) ((__bridge_transfer id)(objc_objectptr_t)(o))
 189 #   define objc_unretainedObject(o) ((__bridge id)(objc_objectptr_t)(o))
 190 #   define objc_unretainedPointer(o) ((__bridge objc_objectptr_t)(id)(o))
 191 #else
 192 #   define objc_retainedObject(o) ((id)(objc_objectptr_t)(o))
 193 #   define objc_unretainedObject(o) ((id)(objc_objectptr_t)(o))
 194 #   define objc_unretainedPointer(o) ((objc_objectptr_t)(id)(o))
 195 #endif
 196
 197
 198 #if !__OBJC2__
 199
 200 // The following declarations are provided here for source compatibility.
 201
 202 #if defined(__LP64__)
 203     typedef long arith_t;
 204     typedef unsigned long uarith_t;
 205 #   define ARITH_SHIFT 32
 206 #else
 207     typedef int arith_t;
 208     typedef unsigned uarith_t;
 209 #   define ARITH_SHIFT 16
 210 #endif
 211
 212 typedef char *STR;
 213
 214 #define ISSELECTOR(sel) sel_isMapped(sel)
 215 #define SELNAME(sel)    sel_getName(sel)
 216 #define SELUID(str)     sel_getUid(str)
 217 #define NAMEOF(obj)     object_getClassName(obj)
 218 #define IV(obj)         object_getIndexedIvars(obj)
 219
 220 #endif
 221
 222 #endif  /* _OBJC_OBJC_H_ */