object.h 12.1 KB
Newer Older
Simon Morlat's avatar
Simon Morlat committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
/*
	belle-sip - SIP (RFC3261) library.
    Copyright (C) 2010  Belledonne Communications SARL

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef belle_sip_object_h
#define belle_sip_object_h

22 23
#include "belle-sip/defs.h"

Simon Morlat's avatar
Simon Morlat committed
24 25 26 27 28 29 30 31 32
/*
 * typedefs, macros and functions for object definition and manipulation.
 */

#define BELLE_SIP_TYPE_ID(_type) _type##_id

typedef unsigned int belle_sip_type_id_t;

#define BELLE_SIP_DECLARE_TYPES_BEGIN(namezpace,unique_namespace_id) \
Simon Morlat's avatar
Simon Morlat committed
33 34
	enum namezpace##type_ids{\
		namezpace##type_id_first=unique_namespace_id,
Simon Morlat's avatar
Simon Morlat committed
35 36 37

#define BELLE_SIP_DECLARE_TYPES_END };

Simon Morlat's avatar
Simon Morlat committed
38
#define BELLE_SIP_OBJECT_VPTR_NAME(object_type)	object_type##_vptr
Simon Morlat's avatar
Simon Morlat committed
39

Simon Morlat's avatar
Simon Morlat committed
40 41 42 43
#define BELLE_SIP_OBJECT_VPTR_TYPE(object_type)	object_type##_vptr_t

#define BELLE_SIP_DECLARE_VPTR(object_type) \
	typedef belle_sip_object_vptr_t BELLE_SIP_OBJECT_VPTR_TYPE(object_type);\
Ghislain MARY's avatar
Ghislain MARY committed
44
	BELLESIP_VAR_EXPORT BELLE_SIP_OBJECT_VPTR_TYPE(object_type) BELLE_SIP_OBJECT_VPTR_NAME(object_type);
Simon Morlat's avatar
Simon Morlat committed
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72

#define BELLE_SIP_DECLARE_CUSTOM_VPTR_BEGIN(object_type, parent_type) \
	typedef struct object_type##_vptr_struct BELLE_SIP_OBJECT_VPTR_TYPE(object_type);\
	extern BELLE_SIP_OBJECT_VPTR_TYPE(object_type) BELLE_SIP_OBJECT_VPTR_NAME(object_type);\
	struct object_type##_vptr_struct{\
		BELLE_SIP_OBJECT_VPTR_TYPE(parent_type) base;

#define BELLE_SIP_DECLARE_CUSTOM_VPTR_END };

#define BELLE_SIP_INSTANCIATE_CUSTOM_VPTR(object_type) \
	BELLE_SIP_OBJECT_VPTR_TYPE(object_type) BELLE_SIP_OBJECT_VPTR_NAME(object_type)


#define BELLE_SIP_VPTR_INIT(object_type,parent_type,unowned) \
		BELLE_SIP_TYPE_ID(object_type), \
		#object_type,\
		unowned,\
		(belle_sip_object_vptr_t*)&BELLE_SIP_OBJECT_VPTR_NAME(parent_type), \
		(belle_sip_interface_desc_t**)object_type##interfaces_table


#define BELLE_SIP_INSTANCIATE_VPTR(object_type,parent_type,destroy,clone,marshal,unowned) \
		BELLE_SIP_OBJECT_VPTR_TYPE(object_type) BELLE_SIP_OBJECT_VPTR_NAME(object_type)={ \
		BELLE_SIP_VPTR_INIT(object_type,parent_type,unowned), \
		(belle_sip_object_destroy_t)destroy,	\
		(belle_sip_object_clone_t)clone,	\
		(belle_sip_object_marshal_t)marshal\
		}
Simon Morlat's avatar
Simon Morlat committed
73 74 75 76 77 78

/**
 * belle_sip_object_t is the base object.
 * It is the base class for all belle sip non trivial objects.
 * It owns a reference count which allows to trigger the destruction of the object when the last
 * user of it calls belle_sip_object_unref().
Simon Morlat's avatar
Simon Morlat committed
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
 * 
 * About object lifecycle<br>
 * In belle-sip, objects can be, depending on their types, initially owned, that there are created with a ref count of 1, or
 * initially unowned, that is with reference count of 0. Such objets are also referred as "floating object". They are automatically destroyed
 * by the main loop iteration, so a floating object can be seen as a temporary object, until someones calls belle_sip_object_ref() on it.
 * 
 * In order to know whether a kind of object is initially owned or initially unowned, you can use the test program tester/belle_sip_object_destribe.
 * This tool gives the hierarchy and properties of the object type whose name is supplied in argument. For example:
 * 
 * <pre>./tester/belle_sip_object_describe belle_sip_request_t</pre>
 * 
 * The object memory management depends slightly on whether an object type is created initially owned or not.
 * In order not to be lost and make memory fault or leaks, consider the following rules:
 * 
 * When an object is of type initially unowned:
 * * call belle_sip_object_ref() on it only if you need a pointer to this object to be used outside the scope of the current function.
 * * call belle_sip_object_unref() on it only if you previously called belle_sip_object_ref().
 * 
 * When an object is of type initially owned:
 * * you can safely store its pointer.
 * * use belle_sip_object_unref() when you no longer need it.
 * 
 * Also, keep in mind that most objects of belle-sip are initially unowned, especially 
 * * all objects who are usually required to be used inside another object (for example: an URI is part of a from header, a contact header is part of a message)
 * * all objects whose lifecyle is maintained by the stack: transactions, dialogs.
 * 
 * On the contrary, top level objects whose lifecyle belongs only to the application are initially owned:
 * * belle_sip_provider_t, belle_sip_stack_t, belle_sip_source_t.
 * 
 * Internally, belle-sip objects containing pointers to other objects must take a reference count on the other objects they hold; and leave this reference
 * when they no longer need it. This rule must be strictly followed by developers doing things inside belle-sip.
Simon Morlat's avatar
Simon Morlat committed
110 111
**/
typedef struct _belle_sip_object belle_sip_object_t;
Simon Morlat's avatar
Simon Morlat committed
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
		

typedef void (*belle_sip_object_destroy_t)(belle_sip_object_t*);
typedef void (*belle_sip_object_clone_t)(belle_sip_object_t* obj, const belle_sip_object_t *orig);
typedef int (*belle_sip_object_marshal_t)(belle_sip_object_t* obj, char* buff,unsigned int offset,size_t buff_size);

struct _belle_sip_object_vptr{
	belle_sip_type_id_t id;
	const char *type_name;
	int initially_unowned;
	struct _belle_sip_object_vptr *parent;
	struct belle_sip_interface_desc **interfaces; /*NULL terminated table of */
	belle_sip_object_destroy_t destroy;
	belle_sip_object_clone_t clone;
	belle_sip_object_marshal_t marshal;
};

typedef struct _belle_sip_object_vptr belle_sip_object_vptr_t;

struct _belle_sip_object{
	belle_sip_object_vptr_t *vptr;
	size_t size;
	int ref;
	char* name;
	struct weak_ref *weak_refs;
};

Simon Morlat's avatar
Simon Morlat committed
139 140 141

BELLE_SIP_BEGIN_DECLS

142 143
BELLESIP_VAR_EXPORT belle_sip_object_vptr_t belle_sip_object_t_vptr;		

Simon Morlat's avatar
Simon Morlat committed
144

145
BELLESIP_EXPORT belle_sip_object_t * _belle_sip_object_new(size_t objsize, belle_sip_object_vptr_t *vptr);
Simon Morlat's avatar
Simon Morlat committed
146 147 148 149

#define belle_sip_object_new(_type) (_type*)_belle_sip_object_new(sizeof(_type),(belle_sip_object_vptr_t*)&BELLE_SIP_OBJECT_VPTR_NAME(_type))


Simon Morlat's avatar
Simon Morlat committed
150 151 152 153 154
int belle_sip_object_is_unowed(const belle_sip_object_t *obj);

/**
 * Increments reference counter, which prevents the object from being destroyed.
 * If the object is initially unowed, this acquires the first reference.
Simon Morlat's avatar
Simon Morlat committed
155
 * 
Simon Morlat's avatar
Simon Morlat committed
156
**/
157
BELLESIP_EXPORT belle_sip_object_t * belle_sip_object_ref(void *obj);
Simon Morlat's avatar
Simon Morlat committed
158

jehan's avatar
jehan committed
159
/*#define BELLE_SIP_REF(object,type) (type*)belle_sip_object_ref(object);*/
Simon Morlat's avatar
Simon Morlat committed
160 161 162
/**
 * Decrements the reference counter. When it drops to zero, the object is destroyed.
**/
163
BELLESIP_EXPORT void belle_sip_object_unref(void *obj);
Simon Morlat's avatar
Simon Morlat committed
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188


typedef void (*belle_sip_object_destroy_notify_t)(void *userpointer, belle_sip_object_t *obj_being_destroyed);
/**
 * Add a weak reference to object.
 * When object will be destroyed, then the destroy_notify callback will be called.
 * This allows another object to be informed when object is destroyed, and then possibly
 * cleanups pointer it holds to this object.
**/
belle_sip_object_t *belle_sip_object_weak_ref(void *obj, belle_sip_object_destroy_notify_t destroy_notify, void *userpointer);

/**
 * Remove a weak reference to object.
**/
void belle_sip_object_weak_unref(void *obj, belle_sip_object_destroy_notify_t destroy_notify, void *userpointer);

/**
 * Set object name.
**/
void belle_sip_object_set_name(belle_sip_object_t *obj,const char* name);
/**
 * Get object name.
**/
const char* belle_sip_object_get_name(belle_sip_object_t *obj);

Simon Morlat's avatar
Simon Morlat committed
189 190 191
/*copy the content of ref object to new object, for the part they have in common in their inheritence diagram*/
void _belle_sip_object_copy(belle_sip_object_t *newobj, const belle_sip_object_t *ref);

Simon Morlat's avatar
Simon Morlat committed
192
/**
Simon Morlat's avatar
Simon Morlat committed
193 194 195 196
 * Clone an object.
 * 
 * This clone function makes a deep copy of all object internal structure, so that the new object and the reference object have no dependencies at all.
 * 
Simon Morlat's avatar
Simon Morlat committed
197
**/
198
BELLESIP_EXPORT belle_sip_object_t *belle_sip_object_clone(const belle_sip_object_t *obj);
Simon Morlat's avatar
Simon Morlat committed
199

200 201 202 203 204 205 206
/**
 * Same as #belle_sip_object_clone but with ref count set to 1
 *
**/
belle_sip_object_t *belle_sip_object_clone_and_ref(const belle_sip_object_t *obj);


Simon Morlat's avatar
Simon Morlat committed
207 208 209 210 211 212 213 214 215 216
/**
 * Returns a string describing the inheritance diagram and implemented interfaces of object obj.
**/
char *belle_sip_object_describe(void *obj);

/**
 * Returns a string describing the inheritance diagram and implemented interfaces of an object given its type name.
**/
char *belle_sip_object_describe_type_from_name(const char *name);

217
BELLESIP_EXPORT void *belle_sip_object_cast(belle_sip_object_t *obj, belle_sip_type_id_t id, const char *castname, const char *file, int fileno);
Simon Morlat's avatar
Simon Morlat committed
218

Simon Morlat's avatar
Simon Morlat committed
219 220 221 222 223
/**
 * Returns a newly allocated string representing the object.
 * WHen the object is a sip header, uri or message, this is the textual representation of the header, uri or message.
 * This function internally calls belle_sip_object_marshal().
**/
224
BELLESIP_EXPORT char* belle_sip_object_to_string(belle_sip_object_t* obj);
Simon Morlat's avatar
Simon Morlat committed
225

Simon Morlat's avatar
Simon Morlat committed
226 227 228 229
/**
 * Writes a string representation of the object into the supplied buffer.
 * Same as belle_sip_object_to_string(), but without allocating space for the output string.
**/
Sylvain Berfini's avatar
Sylvain Berfini committed
230
BELLESIP_EXPORT int belle_sip_object_marshal(belle_sip_object_t* obj, char* buff,unsigned int offset,size_t buff_size);
Simon Morlat's avatar
Simon Morlat committed
231

232
BELLESIP_EXPORT int belle_sip_object_is_instance_of(belle_sip_object_t * obj,belle_sip_type_id_t id);
Simon Morlat's avatar
Simon Morlat committed
233 234 235 236 237 238 239

BELLE_SIP_END_DECLS

#define BELLE_SIP_CAST(obj,_type) 		((_type*)belle_sip_object_cast((belle_sip_object_t *)(obj), _type##_id, #_type, __FILE__, __LINE__))

#define BELLE_SIP_OBJECT(obj) BELLE_SIP_CAST(obj,belle_sip_object_t)
#define BELLE_SIP_IS_INSTANCE_OF(obj,_type) belle_sip_object_is_instance_of((belle_sip_object_t*)obj,_type##_id)
Simon Morlat's avatar
Simon Morlat committed
240
#define BELLE_SIP_OBJECT_IS_INSTANCE_OF(obj,_type)	BELLE_SIP_IS_INSTANCE_OF(obj,_type)
Simon Morlat's avatar
Simon Morlat committed
241 242 243 244 245 246 247 248 249 250 251 252 253
#define belle_sip_object_describe_type(type) \
	belle_sip_object_describe_type_from_name(#type)

/*
 * typedefs, macros and functions for interface definition and manipulation.
 */

#define BELLE_SIP_INTERFACE_ID(_interface) _interface##_id

typedef unsigned int belle_sip_interface_id_t;

BELLE_SIP_BEGIN_DECLS

254
BELLESIP_EXPORT void *belle_sip_object_interface_cast(belle_sip_object_t *obj, belle_sip_interface_id_t id, const char *castname, const char *file, int fileno);
Simon Morlat's avatar
Simon Morlat committed
255 256 257 258 259 260 261 262 263 264

int belle_sip_object_implements(belle_sip_object_t *obj, belle_sip_interface_id_t id);

BELLE_SIP_END_DECLS


#define BELLE_SIP_INTERFACE_METHODS_TYPE(interface_name) methods_##interface_name

#define BELLE_SIP_INTERFACE_CAST(obj,_iface) ((_iface*)belle_sip_object_interface_cast((belle_sip_object_t*)(obj),_iface##_id,#_iface,__FILE__,__LINE__))

Simon Morlat's avatar
Simon Morlat committed
265 266
#define BELLE_SIP_IMPLEMENTS(obj,_iface)		belle_sip_object_implements((belle_sip_object_t*)obj,_iface##_id)

Simon Morlat's avatar
Simon Morlat committed
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281

typedef struct belle_sip_interface_desc{
	belle_sip_interface_id_t id;
	const char *ifname;
}belle_sip_interface_desc_t;

#define BELLE_SIP_DECLARE_INTERFACE_BEGIN(interface_name) \
	typedef struct struct##interface_name interface_name;\
	typedef struct struct_methods_##interface_name BELLE_SIP_INTERFACE_METHODS_TYPE(interface_name);\
	struct struct_methods_##interface_name {\
		belle_sip_interface_desc_t desc;\
		

#define BELLE_SIP_DECLARE_INTERFACE_END };

Simon Morlat's avatar
Simon Morlat committed
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308
#define BELLE_SIP_IMPLEMENT_INTERFACE_BEGIN(object_type,interface_name) \
	static BELLE_SIP_INTERFACE_METHODS_TYPE(interface_name)  methods_##object_type##_##interface_name={\
		{ BELLE_SIP_INTERFACE_ID(interface_name),\
		#interface_name },

#define BELLE_SIP_IMPLEMENT_INTERFACE_END };

#define BELLE_SIP_DECLARE_NO_IMPLEMENTED_INTERFACES(object_type)\
	static belle_sip_interface_desc_t * object_type##interfaces_table[]={\
		NULL \
	}

#define BELLE_SIP_DECLARE_IMPLEMENTED_INTERFACES_1(object_type,iface1) \
	static belle_sip_interface_desc_t * object_type##interfaces_table[]={\
		(belle_sip_interface_desc_t*)&methods_##object_type##_##iface1, \
		NULL \
	}

#define BELLE_SIP_DECLARE_IMPLEMENTED_INTERFACES_2(object_type,iface1,iface2) \
	static belle_sip_interface_desc_t * object_type##interfaces_table[]={\
		(belle_sip_interface_desc_t*)&methods_##object_type##_##iface1, \
		(belle_sip_interface_desc_t*)&methods_##object_type##_##iface2, \
		NULL \
	}



Simon Morlat's avatar
Simon Morlat committed
309 310 311

#endif