1  /** Interface to ObjC runtime for GNUStep
  2     Copyright (C) 1995, 1997, 2000, 2002, 2003 Free Software Foundation, Inc.
  3  
  4     Written by:  Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu>
  5     Date: 1995
  6     Written by:  Richard Frith-Macdonald <rfm@gnu.org>
  7     Date: 2002
  8     
  9     This file is part of the GNUstep Base Library.
 10  
 11     This library is free software; you can redistribute it and/or
 12     modify it under the terms of the GNU Lesser General Public
 13     License as published by the Free Software Foundation; either
 14     version 2 of the License, or (at your option) any later version.
 15     
 16     This library is distributed in the hope that it will be useful,
 17     but WITHOUT ANY WARRANTY; without even the implied warranty of
 18     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 19     Library General Public License for more details.
 20     
 21     You should have received a copy of the GNU Lesser General Public
 22     License along with this library; if not, write to the Free
 23     Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 24     Boston, MA 02111 USA.
 25  
 26      AutogsdocSource: Additions/GSObjCRuntime.m
 27  
 28     */ 
 29  
 30  #ifndef __GSObjCRuntime_h_GNUSTEP_BASE_INCLUDE
 31  #define __GSObjCRuntime_h_GNUSTEP_BASE_INCLUDE
 32  
 33  #include <stdio.h>
 34  
 35  #define __GNU_LIBOBJC__
 36  #define OBJC2RUNTIME 1
 37  #ifndef GS_EXPORT
 38  #	define GS_EXPORT extern
 39  #endif
 40  
 41  #if NeXT_RUNTIME
 42   #include <objc/objc.h>
 43   #include <objc/objc-class.h>
 44   #include <objc/objc-runtime.h>
 45   #ifndef _C_ATOM
 46    #define _C_ATOM '%'
 47   #endif
 48   #define _F_CONST    0x01
 49   #define _F_IN       0x01
 50   #define _F_OUT      0x02
 51   #define _F_INOUT    0x03
 52   #define _F_BYCOPY   0x04
 53   #define _F_ONEWAY   0x08
 54   #define _C_CONST    'r'
 55   #define _C_IN       'n'
 56   #define _C_INOUT    'N'
 57   #define _C_OUT      'o'
 58   #define _C_BYCOPY   'O'
 59   #define _C_ONEWAY   'V'
 60  #else				/* GNU Objective C Runtime */
 61   #include <objc/objc.h>
 62   #if defined (__GNU_LIBOBJC__)
 63    #include <objc/runtime.h>
 64   #else
 65    #include <objc/objc-api.h>
 66    #include <objc/encoding.h>
 67   #endif
 68  #endif
 69  
 70  /*
 71   * Hack for older compiler versions that don't have all defines
 72   * needed in  objc-api.h
 73   */
 74  #ifndef	_C_LNG_LNG
 75  #define	_C_LNG_LNG	'q'
 76  #endif
 77  #ifndef	_C_ULNG_LNG
 78  #define	_C_ULNG_LNG	'Q'
 79  #endif
 80  
 81  #if	OBJC2RUNTIME
 82  /* We have a real ObjC2 runtime.
 83   */
 84  #include <objc/runtime.h>
 85  #else
 86  /* We emulate an ObjC2 runtime.
 87   */
 88  #include <ObjectiveC2/objc/runtime.h>
 89  #endif
 90  
 91  #ifdef __cplusplus
 92  extern "C" {
 93  #endif
 94  
 95  @class	NSArray;
 96  @class	NSDictionary;
 97  @class	NSObject;
 98  @class	NSString;
 99  @class	NSValue;
100  
101  #ifndef YES
102  #define YES		1
103  #endif
104  #ifndef NO
105  #define NO		0
106  #endif
107  #ifndef nil
108  #define nil		0
109  #endif
110  
111  #if	!defined(_C_CONST)
112  #define _C_CONST        'r'
113  #endif
114  #if	!defined(_C_IN)
115  #define _C_IN           'n'
116  #endif
117  #if	!defined(_C_INOUT)
118  #define _C_INOUT        'N'
119  #endif
120  #if	!defined(_C_OUT)
121  #define _C_OUT          'o'
122  #endif
123  #if	!defined(_C_BYCOPY)
124  #define _C_BYCOPY       'O'
125  #endif
126  #if	!defined(_C_BYREF)
127  #define _C_BYREF        'R'
128  #endif
129  #if	!defined(_C_ONEWAY)
130  #define _C_ONEWAY       'V'
131  #endif
132  #if	!defined(_C_GCINVISIBLE)
133  #define _C_GCINVISIBLE  '!'
134  #endif
135  
136  /*
137   * Functions for accessing instance variables directly -
138   * We can copy an ivar into arbitrary data,
139   * Get the type encoding for a named ivar,
140   * and copy a value into an ivar.
141   */
142  GS_EXPORT BOOL
143  GSObjCFindVariable(id obj, const char *name,
144  		   const char **type, unsigned int *size, int *offset);
145  
146  GS_EXPORT void
147  GSObjCGetVariable(id obj, int offset, unsigned int size, void *data);
148  
149  GS_EXPORT void
150  GSObjCSetVariable(id obj, int offset, unsigned int size, const void *data);
151  
152  GS_EXPORT NSArray *
153  GSObjCMethodNames(id obj, BOOL recurse);
154  
155  GS_EXPORT NSArray *
156  GSObjCVariableNames(id obj, BOOL recurse);
157  
158  /**
159   * <p>A Behavior can be seen as a "Protocol with an implementation" or a
160   * "Class without any instance variables".  A key feature of behaviors
161   * is that they give a degree of multiple inheritance.
162   * </p>
163   * <p>Behavior methods, when added to a class, override the class's
164   * superclass methods, but not the class's methods.
165   * </p>
166   * <p>Whan a behavior class is added to a receiver class, not only are the
167   * methods defined in the behavior class added, but the methods from the
168   * behavior's class hierarchy are also added (unless already present).
169   * </p>
170   * <p>It's not the case that a class adding behaviors from another class
171   * must have "no instance vars".  The receiver class just has to have the
172   * same layout as the behavior class (optionally with some additional
173   * ivars after those of the behavior class).
174   * </p>
175   * <p>This function provides Behaviors without adding any new syntax to
176   * the Objective C language.  Simply define a class with the methods you
177   * want to add, then call this function with that class as the behavior
178   * argument.
179   * </p>
180   * <p>This function should be called in the +initialize method of the receiver.
181   * </p>
182   * <p>If you add several behaviors to a class, be aware that the order of
183   * the additions is significant.
184   * </p>
185   */
186  GS_EXPORT void
187  GSObjCAddClassBehavior(Class receiver, Class behavior);
188  
189  /**
190   * <p>An Override can be seen as a "category implemented as a separate class
191   * and manually added to the receiver class under program control, rather
192   * than automatically added by the compiler/runtime.
193   * </p>
194   * <p>Override methods, when added to a receiver class, replace the class's
195   * class's methods of the same name (or are added if the class did not define
196   * methods with that name).
197   * </p>
198   * <p>It's not the case that a class adding overrides from another class
199   * must have "no instance vars".  The receiver class just has to have the
200   * same layout as the override class (optionally with some additional
201   * ivars after those of the override class).
202   * </p>
203   * <p>This function provides overrides without adding any new syntax to
204   * the Objective C language.  Simply define a class with the methods you
205   * want to add, then call this function with that class as the override
206   * argument.
207   * </p>
208   * <p>This function should usually be called in the +initialize method
209   * of the receiver.
210   * </p>
211   * <p>If you add several overrides to a class, be aware that the order of
212   * the additions is significant.
213   * </p>
214   */
215  GS_EXPORT void
216  GSObjCAddClassOverride(Class receiver, Class override);
217  
218  /** Turn on (YES), off (NO) or test (-1) behavior debugging.
219   */
220  GS_EXPORT BOOL GSObjCBehaviorDebug(int setget);
221  
222  GS_EXPORT NSValue *
223  GSObjCMakeClass(NSString *name, NSString *superName, NSDictionary *iVars);
224  
225  GS_EXPORT void
226  GSObjCAddClasses(NSArray *classes);
227  
228  /**
229   * Given a NULL terminated list of methods, add them to the class.<br />
230   * If the method already exists in a superclass, the new version overrides
231   * that one, but if the method already exists in the class itsself, the
232   * new one is quietly ignored (replace==NO) or replaced with the new
233   * version (if replace==YES).<br />
234   * To add class methods, cls should be the metaclass of the class to
235   * which the methods are being added.
236   */
237  GS_EXPORT void
238  GSObjCAddMethods(Class cls, Method *list, BOOL replace);
239  
240  /*
241   * Functions for key-value encoding ... they access values in an object
242   * either by selector or directly, but do so using NSNumber for the
243   * scalar types of data.
244   */
245  GS_EXPORT id
246  GSObjCGetVal(NSObject *self, const char *key, SEL sel,
247    const char *type, unsigned size, int offset);
248  
249  GS_EXPORT void
250  GSObjCSetVal(NSObject *self, const char *key, id val, SEL sel,
251    const char *type, unsigned size, int offset);
252  
253  /*
254   * This section includes runtime functions
255   * to query and manipulate the ObjC runtime structures.
256   * These functions take care to not use ObjC code so
257   * that they can safely be used in +(void)load implementations
258   * where applicable.
259   */
260  
261  /**
262   * Deprecated ... use objc_getClassList()
263   */
264  GS_EXPORT unsigned int
265  GSClassList(Class *buffer, unsigned int max, BOOL clearCache);
266  
267  /**
268   * GSObjCClass() is deprecated ... use object_getClass()
269   */
270  GS_EXPORT Class GSObjCClass(id obj);
271  
272  /**
273   * GSObjCSuper() is deprecated ... use class_getSuperclass()
274   */
275  GS_EXPORT Class GSObjCSuper(Class cls);
276  
277  /**
278   * GSObjCIsInstance() is deprecated ... use object_getClass()
279   * in conjunction with class_isMetaClass()
280   */
281  GS_EXPORT BOOL GSObjCIsInstance(id obj);
282  
283  /**
284   * GSObjCIsClass() is deprecated ... use object_getClass()
285   * in conjunction with class_isMetaClass()
286   */
287  GS_EXPORT BOOL GSObjCIsClass(Class cls);
288  
289  /**
290   * Test to see if class inherits from another class
291   * The argument to this function must NOT be nil.
292   */
293  GS_EXPORT BOOL GSObjCIsKindOf(Class cls, Class other);
294  
295  /**
296   * GSClassFromName() is deprecated ... use objc_lookUpClass()
297   */
298  GS_EXPORT Class GSClassFromName(const char *name);
299  
300  /**
301   * GSNameFromClass() is deprecated ... use class_getName()
302   */
303  GS_EXPORT const char *GSNameFromClass(Class cls);
304  
305  /**
306   * GSClassNameFromObject() is deprecated ... use object_getClass()
307   * in conjunction with class_getName()
308   */
309  GS_EXPORT const char *GSClassNameFromObject(id obj);
310  
311  /**
312   * GSNameFromSelector() is deprecated ... use sel_getName()
313   */
314  GS_EXPORT const char *GSNameFromSelector(SEL sel);
315  
316  /**
317   * GSSelectorFromName() is deprecated ... use sel_getUid()
318   */
319  GS_EXPORT SEL
320  GSSelectorFromName(const char *name);
321  
322  /**
323   * Return the selector for the specified name and types.<br />
324   * Returns a nul pointer if the name is nul.<br />
325   * Creates a new selector if necessary.<br />
326   * Code must NOT rely on this providing a selector with type information.
327   */
328  GS_EXPORT SEL
329  GSSelectorFromNameAndTypes(const char *name, const char *types);
330  
331  /**
332   * Return the type information from the specified selector.<br />
333   * May return a nul pointer if the selector was a nul pointer or if it
334   * was not typed (or if the runtime does not support typed selectors).<br />
335   * Code must NOT rely on this providing any type information.
336   */
337  GS_EXPORT const char *
338  GSTypesFromSelector(SEL sel);
339  
340  /**
341   * Compare only the type information ignoring qualifiers, the frame layout
342   * and register markers.  Unlike sel_types_match, this function also
343   * handles comparisons of types with and without any layout information.
344   */
345  GS_EXPORT BOOL
346  GSSelectorTypesMatch(const char *types1, const char *types2);
347  
348  /** Takes full type information and skips forward to the actual type
349   * as specified in the _C_... constants.
350   */
351  GS_EXPORT const char *
352  GSSkipTypeQualifierAndLayoutInfo(const char *types);
353  
354  /**
355   * Returns a protocol object with the corresponding name.
356   * This function searches the registered classes for any protocol
357   * with the supplied name.  If one is found, it is cached in
358   * for future requests.  If efficiency is a factor then use
359   * GSRegisterProtocol() to insert a protocol explicitly into the cache
360   * used by this function.  If no protocol is found this function returns
361   * nil.
362   */
363  GS_EXPORT Protocol *
364  GSProtocolFromName(const char *name);
365  
366  /**
367   * Registers proto in the cache used by GSProtocolFromName().
368   */
369  GS_EXPORT void
370  GSRegisterProtocol(Protocol *proto);
371  
372  /**
373   * A variant of protocol_getMethodDescription which recursively searches
374   * parent protocols if the requested selector isn't found in the given
375   * protocol.
376   *
377   * Returns a {NULL, NULL} structure if the requested selector couldn't be
378   * found.
379   */
380  GS_EXPORT struct objc_method_description
381  GSProtocolGetMethodDescriptionRecursive(Protocol *aProtocol, SEL aSel, BOOL isRequired, BOOL isInstance);
382  
383  /*
384   * Unfortunately the definition of the symbols
385   * 'Method(_t)', 'MethodList(_t)'  and 'IVar(_t)'
386   * are incompatible between the GNU and NeXT/Apple runtimes.
387   * We introduce GSMethod, GSMethodList and GSIVar to allow portability.
388   */
389  typedef Method	GSMethod;
390  typedef Ivar	GSIVar;
391  
392  /**
393   * Returns the pointer to the method structure
394   * for the selector in the specified class.
395   * Depending on searchInstanceMethods, this function searches
396   * either instance or class methods.
397   * Depending on searchSuperClassesm this function searches
398   * either the specified class only or also its superclasses.<br/>
399   * To obtain the implementation pointer IMP use returnValue->method_imp
400   * which should be safe across all runtimes.<br/>
401   * It should be safe to use this function in +load implementations.<br/>
402   * This function should currently (June 2004) be considered WIP.
403   * Please follow potential changes (Name, parameters, ...) closely until
404   * it stabilizes.
405   */
406  GS_EXPORT GSMethod
407  GSGetMethod(Class cls, SEL sel,
408  	    BOOL searchInstanceMethods,
409  	    BOOL searchSuperClasses);
410  
411  /**
412   * Deprecated .. does nothing.
413   */
414  GS_EXPORT void
415  GSFlushMethodCacheForClass (Class cls);
416  
417  /**
418   * Deprecated .. use class_getInstanceVariable()
419   */
420  GS_EXPORT GSIVar
421  GSCGetInstanceVariableDefinition(Class cls, const char *name);
422  
423  /**
424   * Deprecated .. use class_getInstanceVariable()
425   */
426  GS_EXPORT GSIVar
427  GSObjCGetInstanceVariableDefinition(Class cls, NSString *name);
428  
429  /**
430   * GSObjCVersion() is deprecated ... use class_getVersion()
431   */
432  GS_EXPORT int GSObjCVersion(Class cls);
433  
434  /**
435   * Quickly return autoreleased data storage area.
436   */
437  GS_EXPORT void *
438  GSAutoreleasedBuffer(unsigned size);
439  
440  /**
441   * <p>Prints a message to fptr using the format string provided and any
442   * additional arguments.  The format string is interpreted as by
443   * the NSString formatted initialisers, and understands the '%@' syntax
444   * for printing an object.
445   * </p>
446   * <p>The data is written to the file pointer in the default CString
447   * encoding if possible, as a UTF8 string otherwise.
448   * </p>
449   * <p>This function is recommended for printing general log messages.
450   * For debug messages use NSDebugLog() and friends.  For error logging
451   * use NSLog(), and for warnings you might consider NSWarnLog().
452   * </p>
453   */
454  GS_EXPORT BOOL
455  GSPrintf (FILE *fptr, NSString *format, ...);
456  
457  
458  
459  GS_EXPORT NSArray *
460  GSObjCAllSubclassesOfClass(Class cls);
461  
462  GS_EXPORT NSArray *
463  GSObjCDirectSubclassesOfClass(Class cls);
464  
465  /** Function to change the class of the specified instance to newClass.
466   * This handles memory debugging issues in GNUstep-base and also
467   * deals with class finalisation issues in a garbage collecting
468   * environment, so you should use this function rather than attempting
469   * to swizzle class pointers directly.
470   */
471  GS_EXPORT void
472  GSClassSwizzle(id instance, Class newClass);
473  
474  GS_EXPORT const char *
475  GSLastErrorStr(long error_id);
476  
477  
478  
479  #ifndef	GS_MAX_OBJECTS_FROM_STACK
480  /**
481   * The number of objects to try to get from varargs into an array on
482   * the stack ... if there are more than this, use the heap.
483   * NB. This MUST be a multiple of 2
484   */
485  #define	GS_MAX_OBJECTS_FROM_STACK	128
486  #endif
487  
488  /**
489   * <p>This is a macro designed to minimise the use of memory allocation and
490   * deallocation when you need to work with a vararg list of objects.<br />
491   * The objects are unpacked from the vararg list into two 'C' arrays and
492   * then a code fragment you specify is able to make use of them before
493   * that 'C' array is destroyed. 
494   * </p>
495   * <p>The firstObject argument is the name of the formal parameter in your
496   * method or function which precedes the ', ...' denoting variable args.
497   * </p>
498   * <p>The code argument is a piece of objective-c code to be executed to
499   * make use of the objects stored in the 'C' arrays.<br />
500   * When this code is called the unsigned integer '__count' will contain the
501   * number of objects unpacked, the pointer '__objects' will point to
502   * the first object in each pair, and the pointer '__pairs' will point
503   * to an array containing the second halves of the pairs of objects
504   * whose first halves are in '__objects'.<br />
505   * This lets you pack a list of the form 'key, value, key, value, ...'
506   * into an array of keys and an array of values.
507   * </p>
508   */
509  #define GS_USEIDPAIRLIST(firstObject, code...) ({\
510    va_list	__ap; \
511    unsigned int	__max = GS_MAX_OBJECTS_FROM_STACK; \
512    unsigned int	__count = 0; \
513    id		__buf[__max]; \
514    id		*__objects = __buf; \
515    id		*__pairs = &__objects[__max/2]; \
516    id		__obj = firstObject; \
517    va_start(__ap, firstObject); \
518    while (__obj != nil && __count < __max) \
519      { \
520        if ((__count % 2) == 0) \
521  	{ \
522  	  __objects[__count/2] = __obj; \
523  	} \
524        else \
525  	{ \
526  	  __pairs[__count/2] = __obj; \
527  	} \
528        __obj = va_arg(__ap, id); \
529        if (++__count == __max) \
530  	{ \
531  	  while (__obj != nil) \
532  	    { \
533  	      __count++; \
534  	      __obj = va_arg(__ap, id); \
535  	    } \
536  	} \
537      } \
538    if ((__count % 2) == 1) \
539      { \
540        __pairs[__count/2] = nil; \
541        __count++; \
542      } \
543    va_end(__ap); \
544    if (__count > __max) \
545      { \
546        unsigned int	__tmp; \
547        __objects = (id*)malloc(__count*sizeof(id)); \
548        __pairs = &__objects[__count/2]; \
549        __objects[0] = firstObject; \
550        va_start(__ap, firstObject); \
551        for (__tmp = 1; __tmp < __count; __tmp++) \
552  	{ \
553  	  if ((__tmp % 2) == 0) \
554  	    { \
555  	      __objects[__tmp/2] = va_arg(__ap, id); \
556  	    } \
557  	  else \
558  	    { \
559  	      __pairs[__tmp/2] = va_arg(__ap, id); \
560  	    } \
561  	} \
562        va_end(__ap); \
563      } \
564    code; \
565    if (__objects != __buf) free(__objects); \
566  })
567  
568  /**
569   * <p>This is a macro designed to minimise the use of memory allocation and
570   * deallocation when you need to work with a vararg list of objects.<br />
571   * The objects are unpacked from the vararg list into a 'C' array and
572   * then a code fragment you specify is able to make use of them before
573   * that 'C' array is destroyed. 
574   * </p>
575   * <p>The firstObject argument is the name of the formal parameter in your
576   * method or function which precedes the ', ...' denoting variable args.
577   * </p>
578   * <p>The code argument is a piece of objective-c code to be executed to
579   * make use of the objects stored in the 'C' array.<br />
580   * When this code is called the unsigned integer '__count' will contain the
581   * number of objects unpacked, and the pointer '__objects' will point to
582   * the unpacked objects, ie. firstObject followed by the vararg arguments
583   * up to (but not including) the first nil.
584   * </p>
585   */
586  #define GS_USEIDLIST(firstObject, code...) ({\
587    va_list	__ap; \
588    unsigned int	__max = GS_MAX_OBJECTS_FROM_STACK; \
589    unsigned int	__count = 0; \
590    id		__buf[__max]; \
591    id		*__objects = __buf; \
592    id		__obj = firstObject; \
593    va_start(__ap, firstObject); \
594    while (__obj != nil && __count < __max) \
595      { \
596        __objects[__count] = __obj; \
597        __obj = va_arg(__ap, id); \
598        if (++__count == __max) \
599  	{ \
600  	  while (__obj != nil) \
601  	    { \
602  	      __count++; \
603  	      __obj = va_arg(__ap, id); \
604  	    } \
605  	} \
606      } \
607    va_end(__ap); \
608    if (__count > __max) \
609      { \
610        unsigned int	__tmp; \
611        __objects = (id*)NSZoneMalloc(NSDefaultMallocZone(),__count*sizeof(id)); \
612        va_start(__ap, firstObject); \
613        __objects[0] = firstObject; \
614        for (__tmp = 1; __tmp < __count; __tmp++) \
615  	{ \
616  	  __objects[__tmp] = va_arg(__ap, id); \
617  	} \
618        va_end(__ap); \
619      } \
620    code; \
621    if (__objects != __buf) NSZoneFree (NSDefaultMallocZone(),__objects); \
622  })
623  
624  
625  #ifdef __cplusplus
626  }
627  #endif
628  
629  #endif /* __GSObjCRuntime_h_GNUSTEP_BASE_INCLUDE */