dev • api

Gambas Programming Interface

Index By Category

Array Objects Management
Calling Functions
Class Description
Class Management
Collection Objects Management
Component Management
Conversion Functions
Datatypes Constants
Date & Time Management
Defered Routines
Enumeration Management
Error Management
Event Management
File Management
Gambas Value Datatype
Hash Tables Management
Hook Management
Memory Arrays Management
Memory Management
Method & Property Signatures
Methods Implementation
Object Management
Property Implementation
Returning Strings
Returning Values
Special Methods
Storing Values In Memory
Stream Management
String Management
System & Application Information
Timer Management
Unknown Special Method Management
Watching File Descriptors

Index By Name

ARG
BEGIN_METHOD
BEGIN_METHOD_VOID
BEGIN_PROPERTY
DECLARE_EVENT
DECLARE_METHOD
DECLARE_PROPERTY
END_METHOD
END_PROPERTY
GB.Add
GB.AddString
GB.Alloc
GB.Application.Name
GB.Application.Path
GB.Application.Startup
GB.Application.Title
GB.Application.Version
GB.Array.Add
GB.Array.Count
GB.Array.Get
GB.Array.New
GB.Attach
GB.AutoCreate
GB.Call
GB.CanRaise
GB.CheckObject
GB.CheckPost
GB.Collection.Count
GB.Collection.Get
GB.Collection.New
GB.Collection.Set
GB.Conv
GB.ConvString
GB.Count
GB.CurrentComponent
GB.Detach
GB.Error
GB.ExistClass
GB.ExistFile
GB.ExtendString
GB.FileName
GB.FindClass
GB.Free
GB.FreeArray
GB.FreeString
GB.GetClass
GB.GetClassName
GB.GetEnum
GB.GetEvent
GB.GetFunction
GB.GetInterface
GB.GetTempDir
GB.GetTime
GB.GetUnknown
GB.HashTable.Add
GB.HashTable.Count
GB.HashTable.Enum
GB.HashTable.Free
GB.HashTable.Get
GB.HashTable.New
GB.HashTable.Remove
GB.Hook
GB.Insert
GB.Is
GB.IsProperty
GB.ListEnum
GB.LoadComponent
GB.LoadFile
GB.MakeDate
GB.MakeDateFromTime
GB.MatchString
GB.New
GB.NewArray
GB.NewString
GB.NewZeroString
GB.NextEnum
GB.NParam
GB.NumberFromString
GB.NumberToString
GB.Post
GB.Propagate
GB.Push
GB.Raise
GB.RaiseTimer
GB.RealFileName
GB.Realloc
GB.Ref
GB.ReleaseFile
GB.Remove
GB.ReturnBoolean
GB.ReturnConstString
GB.ReturnConstZeroString
GB.ReturnDate
GB.ReturnFloat
GB.ReturnInteger
GB.ReturnLong
GB.ReturnNewString
GB.ReturnNewZeroString
GB.ReturnNull
GB.ReturnObject
GB.ReturnPtr
GB.ReturnString
GB.SplitDate
GB.StopAllEnum
GB.StopEnum
GB.Store
GB.StoreObject
GB.StoreString
GB.StoreVariant
GB.strcasecmp
GB.Stream.Init
GB.StringLength
GB.strncasecmp
GB.SubstAdd
GB.SubstString
GB.System.Charset
GB.System.Language
GB.tolower
GB.toupper
GB.ToZeroString
GB.Unref
GB.UnRefKeep
GB.Watch
GB_ARRAY
GB_AUTO_CREATABLE
GB_BASE
GB_BOOLEAN
GB_CLASS
GB_COLLECTION
GB_COMP_BINARY
GB_COMP_TEXT
GB_CONSTANT
GB_DATE
GB_DATE_SERIAL
GB_DECLARE
GB_DESC
GB_END_DECLARE
GB_ERR_ARG
GB_ERR_BOUND
GB_ERR_NPROPERTY
GB_ERR_NSYMBOL
GB_ERR_TYPE
GB_EVENT
GB_FLOAT
GB_FUNCTION
GB_HASHTABLE
GB_HASHTABLE_ENUM_FUNC
GB_HOOK_CHECK
GB_HOOK_ERROR
GB_HOOK_LANG
GB_HOOK_LOOP
GB_HOOK_MAIN
GB_HOOK_POST
GB_HOOK_QUIT
GB_HOOK_TIMER
GB_HOOK_WAIT
GB_HOOK_WATCH
GB_INHERITS
GB_INTEGER
GB_LONG
GB_METHOD
GB_NB_LOCAL
GB_NB_READ_ALL
GB_NB_READ_FLOAT
GB_NB_READ_HEX_BIN
GB_NB_READ_INT_LONG
GB_NB_READ_INTEGER
GB_NB_READ_LONG
GB_NOT_CREATABLE
GB_OBJECT
GB_POINTER
GB_PROPERTY
GB_PROPERTY_READ
GB_PROPERTY_SELF
GB_SINGLE
GB_STATIC_METHOD
GB_STATIC_PROPERTY
GB_STATIC_PROPERTY_READ
GB_STATIC_PROPERTY_SELF
GB_STREAM
GB_STREAM_DESC
GB_STRING
GB_SUBST_CALLBACK
GB_T_BOOLEAN
GB_T_BYTE
GB_T_CSTRING
GB_T_DATE
GB_T_FLOAT
GB_T_INTEGER
GB_T_LONG
GB_T_NULL
GB_T_OBJECT
GB_T_POINTER
GB_T_SHORT
GB_T_SINGLE
GB_T_STRING
GB_T_VARIANT
GB_T_VOID
GB_TIMER
GB_TYPE
GB_VALUE
GB_VARIANT
GB_VIRTUAL_CLASS
GB_WATCH_CALLBACK
GB_WATCH_NONE
GB_WATCH_READ
GB_WATCH_READ_WRITE
GB_WATCH_WRITE
LENGTH
MISSING
PLENGTH
PROP
PSTRING
READ_PROPERTY
RETURN_SELF
STRING
VARG
VARGOPT
VPROP

TODO

/* The following symbols must be declared with EXPORT in a component:
   - GB
   - GB_INIT()
   - GB_EXIT()
   - GB_CLASSES
   - The component interface if present
*/

/* Auto creatable class macro */

#define GB_AUTO_CREATABLE() { GB_AUTO_CREATABLE_ID }


/* Symbol description prefixes */

#define GB_PROPERTY_ID          'p'
#define GB_METHOD_ID            'm'
#define GB_CONSTANT_ID          'C'
#define GB_EVENT_ID             ':'
#define GB_ENUM_ID              '#'
#define GB_STATIC_PROPERTY_ID   'P'
#define GB_STATIC_METHOD_ID     'M'


/* Symbol description macros */

#define GB_STATIC_FAST_METHOD(symbol, type, exec, signature) \
	{ "M!" symbol, (intptr_t)type, (intptr_t)exec, (intptr_t)signature }

#define GB_INTERFACE(symbol, pointer) \
	{ "C_@" symbol, (intptr_t)"p", (intptr_t)pointer }

/* Macro used for calling a parameter-less implementation method */

#define CALL_METHOD_VOID(_name) _name(_object, NULL)


/* Macros to get the value of an argument or a property */

#define VALUE(_arg) ((_arg)->value)
#define VARG(_p) VALUE(ARG(_p))
#define VPROP(_p) VALUE(PROP(_p))


/* Macros to get a string argument */

#define STRING(_arg) (VARG(_arg).addr + VARG(_arg).start)
#define LENGTH(_arg) (VARG(_arg).len)


/* Macros to get a string property */

#define PSTRING() (VPROP(GB_STRING).addr + VPROP(GB_STRING).start)
#define PLENGTH() (VPROP(GB_STRING).len)


/* Macro to get an optional argument */

#define VARGOPT(_arg, _default) (MISSING(_arg) ? (_default) : VARG(_arg))


/* Casting macro. Usable only in an implementation function */

#define OBJECT(type) ((type *)_object)


/* Macro for returning itself. Usable only in an implementation function */

#define RETURN_SELF()  GB.ReturnSelf(_object)


/* Macro for declaring a variable used for storing an event identifier */

#define DECLARE_EVENT(_event) static int _event


/* Macro to help accessing enumeration index. Use only in an enumeration method implementation */

#define ENUM(_type)  (*((_type *)GB.GetEnum()))


/* Structure used for describing a class */

typedef
	struct {
		const char *name;
		intptr_t val1;
		intptr_t val2;
		intptr_t val3;
		intptr_t val4;
		intptr_t val5;
		}
	GB_DESC;


/* Type of a method implementation function */

typedef
	void GB_METHOD_FUNC(void *, void *);


/* Type of a property implementation function */

typedef
	void GB_PROPERTY_FUNC(void *, void *);


/* Macro for declaring a method implementation function */

#define DECLARE_METHOD(_method) GB_METHOD_FUNC _method


/* Macro for declaring a property implementation function */

#define DECLARE_PROPERTY(_property) GB_PROPERTY_FUNC _property


/* Constants used with the GB.Hook() API function */

#define GB_HOOK_MAX 10

#define GB_HOOK_MAIN      1
#define GB_HOOK_LOOP      2
#define GB_HOOK_WAIT      3
#define GB_HOOK_TIMER     4
#define GB_HOOK_LANG      5
#define GB_HOOK_WATCH     6
#define GB_HOOK_POST      7
#define GB_HOOK_QUIT      8
#define GB_HOOK_ERROR     9
#define GB_HOOK_TIMEOUT   10

/* Constants that represent interpreter signals catched by GB_SIGNAL function */

#define GB_SIGNAL_DEBUG_BREAK         1
#define GB_SIGNAL_DEBUG_CONTINUE      2
#define GB_SIGNAL_DEBUG_FORWARD				3


/* Constants used with the GB.Watch() API function */

#define GB_WATCH_NONE         0
#define GB_WATCH_READ         1
#define GB_WATCH_WRITE        2


/* Type of a generic callback */

typedef
	void (*GB_CALLBACK)();


/* Type of a watch callback function */

typedef
	void (*GB_WATCH_CALLBACK)(int, int, intptr_t);


/* Type of the GB.SubstString() callback */

typedef
	void (*GB_SUBST_CALLBACK)(int, char **, int *);


/* Type of the GB.SubstStringAdd() callback */

typedef
	void (*GB_SUBST_ADD_CALLBACK)(int);


/* Type of the GB.BrowseProject() callback */

typedef
	void (*GB_BROWSE_CALLBACK)(const char *, int64_t);


/* Type of a timer callback */

typedef
	int (*GB_TIMER_CALLBACK)(intptr_t);


/* Type of a posted function */

typedef
	void (*GB_POST_FUNC)();


/* A structure for the components of a date */

typedef
	struct {
		short year;
		short month;
		short day;
		short hour;
		short min;
		short sec;
		short weekday;
		short msec;
		}
	GB_DATE_SERIAL;


/* Opaque type of a Gambas interpreted or native function */

typedef
	struct {
		void *object;
		void *desc;
		}
	GB_FUNCTION;

#define GB_FUNCTION_IS_VALID(_func) ((_func)->desc)


/* Opaque type of a Gambas Array */

typedef
	void *GB_ARRAY;


/* Opaque type of a Gambas Collection */

typedef
	void *GB_COLLECTION;


/* Opaque type of a Gambas Collection iterator */

typedef
	struct {
		void *iter1;
		void *iter2;
		}
	GB_COLLECTION_ITER;


/* opaque type of an hash table */

typedef
	void *GB_HASHTABLE;


/* hash table enumeration function */

typedef
	void (*GB_HASHTABLE_ENUM_FUNC)(void *);


/* opaque type for a Stream object */

struct GB_STREAM;

typedef
	struct {
		int (*open)(struct GB_STREAM *stream, const char *path, int mode, void *data);
		int (*close)(struct GB_STREAM *stream);
		int (*read)(struct GB_STREAM *stream, char *buffer, int len);
		int (*getchar)(struct GB_STREAM *stream, char *buffer);
		int (*write)(struct GB_STREAM *stream, char *buffer, int len);
		int (*seek)(struct GB_STREAM *stream, int64_t pos, int whence);
		int (*tell)(struct GB_STREAM *stream, int64_t *pos);
		int (*flush)(struct GB_STREAM *stream);
		int (*eof)(struct GB_STREAM *stream);
		int (*lof)(struct GB_STREAM *stream, int64_t *len);
		int (*handle)(struct GB_STREAM *stream);
		}
	GB_STREAM_DESC;

typedef
	struct {
		GB_STREAM_DESC *desc;
		int64_t _reserved;
		intptr_t _reserved2;
		intptr_t _reserved3;
		}
	GB_STREAM_BASE;

typedef
	struct GB_STREAM {
		GB_STREAM_DESC *desc;
		int64_t _reserved;
		intptr_t _reserved2;
		intptr_t _reserved3;
		void *tag;
		#if __WORDSIZE == 64
		int _free[4];
		#else
		int _free[5];
		#endif
		GB_VARIANT_VALUE _reserved4;
		}
	GB_STREAM;


/* Constants used by the GB.NumberFromString() API function */

#define GB_NB_READ_INTEGER    1
#define GB_NB_READ_LONG       2
#define GB_NB_READ_INT_LONG   3
#define GB_NB_READ_FLOAT      4
#define GB_NB_READ_ALL        7
#define GB_NB_READ_HEX_BIN    8
#define GB_NB_LOCAL           16


/* Constants used by the GB.Collection.New() and GB.HashTable.New() API function */

#define GB_COMP_BINARY      0
#define GB_COMP_NOCASE      1


/* Constant used by GB.ConvString to convert to 32 bits Unicode (that needs some special processing) */

#define GB_SC_UNICODE ((char *)-1)


/* Opaque type for a SubCollection object */

typedef
	void *GB_SUBCOLLECTION;


/* SubCollection description */

typedef
	struct {
		char *klass;
		void *(*get)(void *, const char *);
		int (*exist)(void *, const char *);
		void (*list)(void *, char ***);
		void (*release)(void *, void *);
	}
	GB_SUBCOLLECTION_DESC;


/* Timer object */

typedef
	struct {
		GB_BASE object;
		intptr_t id;
		intptr_t tag;
		int delay;
		GB_TIMER_CALLBACK callback;
		}
	GB_TIMER;


/* A macro for preventing gcc from warning about breaks in the
   strict aliasing rules */

#define POINTER(_pointer) (void **)(void *)_pointer

/* Gambas Application Programming Interface */

typedef
	struct {
		intptr_t version;

		bool (*GetInterface)(const char *, int, void *);

		void *(*Hook)(int, void *);

		bool (*LoadComponent)(const char *);
		bool (*ExistComponent)(const char *);
		char *(*CurrentComponent)(void);
		bool (*GetComponentInfo)(const char *, void **);

		void (*Push)(int, ...);
		bool (*GetFunction)(GB_FUNCTION *, void *, const char *, const char *, const char *);
		GB_VALUE *(*Call)(GB_FUNCTION *, int, int);
		void *(*GetClassInterface)(GB_CLASS, const char *);
		void (*GetProperty)(void *, const char *);
		void (*SetProperty)(void *, const char *, ...);

		bool (*Loop)(int);
		void (*Post)(GB_CALLBACK, intptr_t);
		void (*Post2)(GB_CALLBACK, intptr_t, intptr_t);
		GB_TIMER *(*Every)(int, GB_TIMER_CALLBACK, intptr_t);
		bool (*Raise)(void *, int, int, ...);
		void (*RaiseLater)(void *, int);
		void (*CheckPost)(void);
		bool (*CanRaise)(void *, int);
		int (*GetEvent)(GB_CLASS, const char *);
		char *(*GetLastEventName)();
		void (*RaiseTimer)(void *);
		bool (*Stopped)(void);
		void (*Signal)(int, void *);

		int (*NParam)(void);
		bool (*Conv)(GB_VALUE *, GB_TYPE);
		char *(*GetUnknown)(void);

		void (*Error)(const char *, ...);
		void (*Propagate)(void);

		GB_CLASS (*GetClass)(void *);
		char *(*GetClassName)(void *);
		bool (*ExistClass)(const char *);
		GB_CLASS (*FindClass)(const char *);
		bool (*ExistClassLocal)(const char *);
		GB_CLASS (*FindClassLocal)(const char *);
		bool (*Is)(void *, GB_CLASS);
		void (*Ref)(void *);
		void (*Unref)(void **);
		void (*UnrefKeep)(void **, int);
		void (*Detach)(void *);
		void (*Attach)(void *, void *, const char *);
		void *(*Parent)(void *);
		void *(*New)(GB_CLASS, char *, void *);
		void *(*AutoCreate)(GB_CLASS, int);
		bool (*CheckObject)(void *);

		void *(*GetEnum)();
		void (*StopEnum)();
		void (*ListEnum)(void *);
		bool (*NextEnum)();
		void (*StopAllEnum)(void *);

		void (*Return)(GB_TYPE, ...);
		void (*ReturnInteger)(int);
		void (*ReturnLong)(int64_t);
		void (*ReturnPointer)(void *);
		void (*ReturnBoolean)(int);
		void (*ReturnDate)(GB_DATE *);
		void (*ReturnObject)(void *);
		void (*ReturnNull)(void);
		void (*ReturnFloat)(double);
		void (*ReturnVariant)(GB_VARIANT_VALUE *);
		void (*ReturnConvVariant)();
		void (*ReturnPtr)(GB_TYPE, void *);
		void (*ReturnSelf)(void *);

		void (*ReturnString)(char *);
		void (*ReturnVoidString)(void);
		void (*ReturnConstString)(const char *, int);
		void (*ReturnConstZeroString)(const char *);
		void (*ReturnNewString)(const char *, int);
		void (*ReturnNewZeroString)(const char *);

		char *(*NewString)(const char *, int);
		char *(*NewZeroString)(const char *);
		char *(*TempString)(const char *, int);
		void (*FreeString)(char **);
		char *(*ExtendString)(char *, int);
		char *(*AddString)(char *, const char *, int);
		char *(*AddChar)(char *, char);
		int (*StringLength)(char *);
		char *(*ToZeroString)(GB_STRING *);
		bool (*MatchString)(const char *, int, const char *, int);
		bool (*NumberFromString)(int, const char *, int, GB_VALUE *);
		bool (*NumberToString)(int, double, const char *, char **, int *);
		char *(*Translate)(const char *);

		char *(*SubstString)(const char *, int, GB_SUBST_CALLBACK);
		char *(*SubstStringAdd)(const char *, int, GB_SUBST_ADD_CALLBACK);
		void (*SubstAddCallback)(const char *, int);
		bool (*ConvString)(char **, const char *, int, const char *, const char *);
		char *(*FileName)(char *, int);
		char *(*RealFileName)(char *, int);

		bool (*LoadFile)(const char *, int, char **, int *);
		void (*ReleaseFile)(char *, int);
		char *(*TempDir)(void);
		char *(*TempFile)(const char *);
		bool (*CopyFile)(const char *, const char *);
		void (*BrowseProject)(GB_BROWSE_CALLBACK);

		void (*Store)(GB_TYPE, GB_VALUE *, void *);
		void (*StoreString)(GB_STRING *, char **);
		void (*StoreObject)(GB_OBJECT *, void **);
		void (*StoreVariant)(GB_VARIANT *, void *);
		void (*ReadValue)(GB_VALUE *, void *, GB_TYPE);
		void (*BorrowValue)(GB_VALUE *);
		void (*ReleaseValue)(GB_VALUE *);

		GB_DATE_SERIAL *(*SplitDate)(GB_DATE *);
		bool (*MakeDate)(GB_DATE_SERIAL *, GB_DATE *);
		void (*MakeDateFromTime)(int, int, GB_DATE *);
		bool (*GetTime)(double *, int);

		void (*Watch)(int, int, void *, intptr_t);

		GB_VALUE *(*Eval)(void *, void *);

		void (*Alloc)(void **, int);
		void (*Free)(void **);
		void (*Realloc)(void **, int);

		void (*NewArray)(void *, int, int);
		void (*FreeArray)(void *);
		int (*Count)(void *);
		void *(*Add)(void *);
		void *(*Insert)(void *, int, int);
		void (*Remove)(void *, int, int);

		struct {
			void (*New)(GB_SUBCOLLECTION *, GB_SUBCOLLECTION_DESC *, void *);
			void (*Add)(void *, const char *, int, void *);
			void (*Remove)(void *, const char *, int);
			void *(*Get)(void *, const char *, int);
			void *(*Container)(void *);
			}
		SubCollection;

		int (*ToLower)(int);
		int (*ToUpper)(int);
		int (*StrCaseCmp)(const char *, const char *);
		int (*StrNCaseCmp)(const char *, const char *, int);

		struct {
			char *(*Name)(void);
			char *(*Title)(void);
			char *(*Version)(void);
			char *(*Path)(void);
			GB_CLASS (*StartupClass)(void);
			}
		Application;

		struct {
			char *(*Charset)(void);
			char *(*Language)(void);
			char *(*DomainName)(void);
			bool (*IsRightToLeft)(void);
			char *(*Path)(void);
			}
		System;

		struct {
			void (*New)(GB_ARRAY *, GB_TYPE, int);
			int (*Count)(GB_ARRAY);
			void *(*Add)(GB_ARRAY);
			void *(*Get)(GB_ARRAY, int);
			GB_TYPE (*Type)(GB_ARRAY);
			}
		Array;

		struct {
			void (*New)(GB_COLLECTION *, int);
			int (*Count)(GB_COLLECTION);
			bool (*Set)(GB_COLLECTION, const char *, int, GB_VARIANT *);
			bool (*Get)(GB_COLLECTION, const char *, int, GB_VARIANT *);
			bool (*Enum)(GB_COLLECTION, GB_COLLECTION_ITER *, GB_VARIANT *, char **key, int *len);
			}
		Collection;

		struct {
			void (*New)(GB_HASHTABLE *, int);
			void (*Free)(GB_HASHTABLE *);
			int (*Count)(GB_HASHTABLE);
			void (*Add)(GB_HASHTABLE, const char *, int, void *);
			void (*Remove)(GB_HASHTABLE, const char *, int);
			bool (*Get)(GB_HASHTABLE, const char *, int, void **);
			void (*Enum)(GB_HASHTABLE, GB_HASHTABLE_ENUM_FUNC);
			}
		HashTable;

		struct {
			GB_STREAM *(*Get)(void *object);
			void (*SetBytesRead)(GB_STREAM *stream, int length);
			void (*SetSwapping)(GB_STREAM *stream, int swap);
			bool (*Block)(GB_STREAM *stream, int block);
			int (*Read)(GB_STREAM *stream, void *addr, int len);
			int (*Write)(GB_STREAM *stream, void *addr, int len);
			}
		Stream;

		struct {
			void (*Start)(int length);
			char *(*End)();
			void (*Add)(const char *src, int len);
			}
		String;

		struct {
			char *(*GetCurrentPosition)();
			}
		Debug;

		}
	GB_INTERFACE;


/*

  Special methods that can be declared in a class

  _get        array reading operator
  _put        array writing operator
  _new        constructor
  _free       destructor
  _next       next iteration of an enumeration
  _call       called when the object or the class is used as a function
  _unknown    called when the name of the property or method is unknown

*/

/*

  Syntax of a method or event signature

  Gambas datatype      String representation

  BOOLEAN              b
  INTEGER              i
  LONG                 l
  FLOAT                f
  DATE                 d
  STRING               s
  VARIANT              v
  OBJECT               o
  POINTER              p
  Any class            ClassName;

*/

#ifndef NO_GAMBAS_CASE_REPLACEMENT

/* Replacements for case unsensitive comparisons.
   They ensure that case comparison does not use current locale,
   otherwise Turkish speakers will have problems!
*/

#include <string.h>
#include <ctype.h>

#ifdef tolower
#undef tolower
#endif
#ifdef toupper
#undef toupper
#endif
#ifdef strcasecmp
#undef strcasecmp
#endif
#ifdef strncasecmp
#undef strncasecmp
#endif

#define strcasecmp GB.StrCaseCmp
#define strncasecmp GB.StrNCaseCmp
#define toupper GB.ToUpper
#define tolower GB.ToLower

#endif

#endif
}