object.h 22 KB
Newer Older
Simon Morlat's avatar
Simon Morlat committed
1 2
/*
	belle-sip - SIP (RFC3261) library.
3
	Copyright (C) 2010  Belledonne Communications SARL
Simon Morlat's avatar
Simon Morlat committed
4

5 6
	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
7
	the Free Software Foundation, either version 2 of the License, or
8
	(at your option) any later version.
Simon Morlat's avatar
Simon Morlat committed
9

10 11 12 13
	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.
Simon Morlat's avatar
Simon Morlat committed
14

15 16
	You should have received a copy of the GNU General Public License
	along with this program.  If not, see <http://www.gnu.org/licenses/>.
Simon Morlat's avatar
Simon Morlat committed
17 18 19 20 21
*/

#ifndef belle_sip_object_h
#define belle_sip_object_h

22
#include "belle-sip/defs.h"
Ghislain MARY's avatar
Ghislain MARY committed
23
#include "belle-sip/utils.h"
24
#include "belle-sip/list.h"
25

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

30 31
#define BELLE_SIP_DEFAULT_BUFSIZE_HINT 0

Simon Morlat's avatar
Simon Morlat committed
32 33 34 35 36
#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) \
37 38
	enum namezpace##type_ids{\
		namezpace##type_id_first=unique_namespace_id,
Simon Morlat's avatar
Simon Morlat committed
39 40 41

#define BELLE_SIP_DECLARE_TYPES_END };

42
#define BELLE_SIP_OBJECT_VPTR_NAME(object_type)	object_type##_vptr
Simon Morlat's avatar
Simon Morlat committed
43

44 45
#define BELLE_SIP_OBJECT_GET_VPTR_FUNC(object_type) object_type##_vptr_get

46 47 48 49
#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);\
50
	BELLESIP_EXPORT BELLE_SIP_OBJECT_VPTR_TYPE(object_type) * BELLE_SIP_OBJECT_GET_VPTR_FUNC(object_type)(void);
51 52 53

#define BELLE_SIP_DECLARE_CUSTOM_VPTR_BEGIN(object_type, parent_type) \
	typedef struct object_type##_vptr_struct BELLE_SIP_OBJECT_VPTR_TYPE(object_type);\
54
	BELLESIP_EXPORT BELLE_SIP_OBJECT_VPTR_TYPE(object_type) * BELLE_SIP_OBJECT_GET_VPTR_FUNC(object_type)(void); \
55 56 57
	struct object_type##_vptr_struct{\
		BELLE_SIP_OBJECT_VPTR_TYPE(parent_type) base;

58 59 60 61 62 63 64 65 66 67
#define BELLE_SIP_DECLARE_VPTR_NO_EXPORT(object_type) \
	typedef belle_sip_object_vptr_t BELLE_SIP_OBJECT_VPTR_TYPE(object_type);\
	BELLE_SIP_OBJECT_VPTR_TYPE(object_type) * BELLE_SIP_OBJECT_GET_VPTR_FUNC(object_type)(void);

#define BELLE_SIP_DECLARE_CUSTOM_VPTR_BEGIN_NO_EXPORT(object_type, parent_type) \
	typedef struct object_type##_vptr_struct BELLE_SIP_OBJECT_VPTR_TYPE(object_type);\
	BELLE_SIP_OBJECT_VPTR_TYPE(object_type) * BELLE_SIP_OBJECT_GET_VPTR_FUNC(object_type)(void); \
	struct object_type##_vptr_struct{\
		BELLE_SIP_OBJECT_VPTR_TYPE(parent_type) base;

68 69
#define BELLE_SIP_DECLARE_CUSTOM_VPTR_END };

70 71 72 73 74 75
#define BELLE_SIP_INSTANCIATE_CUSTOM_VPTR_BEGIN(object_type) \
	extern BELLE_SIP_OBJECT_VPTR_TYPE(object_type) BELLE_SIP_OBJECT_VPTR_NAME(object_type);\
	BELLE_SIP_OBJECT_VPTR_TYPE(object_type) * BELLE_SIP_OBJECT_GET_VPTR_FUNC(object_type)(void){\
		return &BELLE_SIP_OBJECT_VPTR_NAME(object_type); \
	}\
	BELLE_SIP_OBJECT_VPTR_TYPE(object_type) BELLE_SIP_OBJECT_VPTR_NAME(object_type)={
76

77
#define BELLE_SIP_INSTANCIATE_CUSTOM_VPTR_END };
78 79 80

#define BELLE_SIP_VPTR_INIT(object_type,parent_type,unowned) \
		BELLE_SIP_TYPE_ID(object_type), \
81
		sizeof(object_type), \
82 83
		#object_type,\
		unowned,\
84
		(belle_sip_object_get_vptr_t)BELLE_SIP_OBJECT_GET_VPTR_FUNC(parent_type), \
85 86
		(belle_sip_interface_desc_t**)object_type##interfaces_table

87 88 89 90 91 92 93 94 95 96 97 98 99
#define BELLE_SIP_INSTANCIATE_VPTR2(object_type,parent_type,destroy,clone,marshal,on_first_ref,on_last_ref,unowned) \
static 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,\
	(belle_sip_object_on_first_ref_t)on_first_ref,\
	(belle_sip_object_on_last_ref_t)on_last_ref,\
	BELLE_SIP_DEFAULT_BUFSIZE_HINT\
	}; \
	BELLE_SIP_OBJECT_VPTR_TYPE(object_type) * BELLE_SIP_OBJECT_GET_VPTR_FUNC(object_type)(void){\
		return &BELLE_SIP_OBJECT_VPTR_NAME(object_type); \
	}
100

Simon Morlat's avatar
Simon Morlat committed
101

102 103
#define BELLE_SIP_INSTANCIATE_VPTR(object_type,parent_type,destroy,clone,marshal,unowned) \
		BELLE_SIP_INSTANCIATE_VPTR2(object_type, parent_type, destroy, clone, marshal, NULL, NULL, unowned)
Simon Morlat's avatar
Simon Morlat committed
104 105 106 107 108
/**
 * 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().
109 110 111
 *
 * It contains a generic data store that allows users to store named data in it and retrieve them afterwards.
 *
112 113 114 115
 * 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.
116 117
 *
 * 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_describe.
118
 * This tool gives the hierarchy and properties of the object type whose name is supplied in argument. For example:
119
 *
120
 * <pre>./tester/belle_sip_object_describe belle_sip_request_t</pre>
121
 *
122 123
 * 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:
124
 *
125 126 127
 * 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().
128
 *
129 130 131
 * 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.
132 133
 *
 * Also, keep in mind that most objects of belle-sip are initially unowned, especially
134 135
 * * 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.
136
 *
137 138
 * 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.
139
 *
140 141
 * 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
142 143
**/
typedef struct _belle_sip_object belle_sip_object_t;
144

145 146 147

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);
148
typedef belle_sip_error_code (*belle_sip_object_marshal_t)(belle_sip_object_t* obj, char* buff, size_t buff_size, size_t *offset);
149
typedef struct _belle_sip_object_vptr *(*belle_sip_object_get_vptr_t)(void);
150 151
typedef void (*belle_sip_object_on_first_ref_t)(belle_sip_object_t*);
typedef void (*belle_sip_object_on_last_ref_t)(belle_sip_object_t*);
152 153 154

struct _belle_sip_object_vptr{
	belle_sip_type_id_t id;
155
	size_t size; /*the size of the object - not the vptr size*/
156 157
	const char *type_name;
	int initially_unowned;
158
	belle_sip_object_get_vptr_t get_parent;
159 160 161 162
	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;
163 164
	belle_sip_object_on_first_ref_t on_first_ref; /*called when object is ref'd for the first time*/
	belle_sip_object_on_last_ref_t on_last_ref; /*called in unref() when the last reference of the object remains*/
165
	int tostring_bufsize_hint; /*optimization: you can suggest here the typical size for a to_string() result.*/
166 167 168 169 170 171 172 173 174
};

typedef struct _belle_sip_object_vptr belle_sip_object_vptr_t;

struct _belle_sip_object{
	belle_sip_object_vptr_t *vptr;
	int ref;
	char* name;
	struct weak_ref *weak_refs;
175
	struct belle_sip_object_pool *pool;
176 177
	belle_sip_list_t *pool_iterator;
	belle_sip_list_t *data_store;
178 179
};

Simon Morlat's avatar
Simon Morlat committed
180 181 182

BELLE_SIP_BEGIN_DECLS

183

184
BELLESIP_EXPORT belle_sip_object_t * _belle_sip_object_new(size_t objsize, belle_sip_object_vptr_t *vptr);
185

186 187 188
#ifdef __cplusplus
#define belle_sip_object_new(_type) reinterpret_cast<_type*>(_belle_sip_object_new(sizeof(_type),(belle_sip_object_vptr_t*)BELLE_SIP_OBJECT_GET_VPTR_FUNC(_type)()))
#else
189
#define belle_sip_object_new(_type) (_type*)_belle_sip_object_new(sizeof(_type),(belle_sip_object_vptr_t*)BELLE_SIP_OBJECT_GET_VPTR_FUNC(_type)())
190
#endif
191

192 193 194 195 196 197 198
/**
 * Activates checks on object marshalling.
 * Useful for debug purposes.
 * @param enable TRUE to enable, FALSE to disable.
**/
BELLESIP_EXPORT void belle_sip_object_enable_marshal_check(int enable);

199 200 201 202 203 204 205 206 207 208 209 210
/**
 * Activates an object leak detector. When enabled, belle-sip will reference all created objects.
 * At program termination, application can check if objects remain alive using belle_sip_object_get_object_count() and dump them with
 * belle_sip_object_dump_active_objects().
 * @warning this must not be used in multi-threaded programs (when multiple threads can access belle-sip at the same time)
 * Useful for debug purposes.
 * @param enable TRUE to enable, FALSE to disable.
**/
BELLESIP_EXPORT void belle_sip_object_enable_leak_detector(int enable);

BELLESIP_EXPORT int belle_sip_object_get_object_count(void);

211 212
BELLESIP_EXPORT void belle_sip_object_flush_active_objects(void);

213 214
BELLESIP_EXPORT void belle_sip_object_dump_active_objects(void);

215 216 217 218 219 220
/**
 * Suspend leak detector from this point. If the leak detector wasn't activated, this function does nothing.
 * This can be useful to make object allocation that have to remain active beyond the scope of a test.
**/
BELLESIP_EXPORT void belle_sip_object_inhibit_leak_detector(int yes);

Simon Morlat's avatar
Simon Morlat committed
221 222 223 224 225
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.
226
 *
Simon Morlat's avatar
Simon Morlat committed
227
**/
228
BELLESIP_EXPORT belle_sip_object_t * belle_sip_object_ref(void *obj);
Simon Morlat's avatar
Simon Morlat committed
229 230 231 232

/**
 * Decrements the reference counter. When it drops to zero, the object is destroyed.
**/
233
BELLESIP_EXPORT void belle_sip_object_unref(void *obj);
Simon Morlat's avatar
Simon Morlat committed
234 235 236 237 238 239 240 241 242


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.
**/
243
BELLESIP_EXPORT belle_sip_object_t *belle_sip_object_weak_ref(void *obj, belle_sip_object_destroy_notify_t destroy_notify, void *userpointer);
Simon Morlat's avatar
Simon Morlat committed
244 245 246 247

/**
 * Remove a weak reference to object.
**/
248
BELLESIP_EXPORT void belle_sip_object_weak_unref(void *obj, belle_sip_object_destroy_notify_t destroy_notify, void *userpointer);
Simon Morlat's avatar
Simon Morlat committed
249 250 251 252

/**
 * Set object name.
**/
253 254
BELLESIP_EXPORT void belle_sip_object_set_name(belle_sip_object_t *obj,const char* name);

Simon Morlat's avatar
Simon Morlat committed
255 256 257
/**
 * Get object name.
**/
258
BELLESIP_EXPORT const char* belle_sip_object_get_name(belle_sip_object_t *obj);
Simon Morlat's avatar
Simon Morlat committed
259

Simon Morlat's avatar
Simon Morlat committed
260 261 262
/*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
263
/**
264
 * Clone an object.
265
 *
266
 * 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.
267
 *
Simon Morlat's avatar
Simon Morlat committed
268
**/
269
BELLESIP_EXPORT belle_sip_object_t *belle_sip_object_clone(const belle_sip_object_t *obj);
Simon Morlat's avatar
Simon Morlat committed
270

271 272 273 274 275 276 277
/**
 * 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);


278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298
typedef void  (*belle_sip_data_destroy)(void* data);
typedef void* (*belle_sip_data_clone)(const char* name, void* data);

/**
 * Add an entry to the object's embedded data store, with the key name specified.
 * The destroy function is used when the data is cleaned.
 *
 * If an entry already exists, the existing data will be cleaned by calling its destroy function and the new data will be placed instead.
 *
 * Returns -1 in case of error, 0 in case the insertion was successful, and 1 if existing data was present.
**/
BELLESIP_EXPORT int   belle_sip_object_data_set( belle_sip_object_t *obj, const char* name, void* data, belle_sip_data_destroy destroy_func );

/**
 * Retrieve data that has been stored in the object data store.
**/
BELLESIP_EXPORT void* belle_sip_object_data_get( belle_sip_object_t *obj, const char* name );

/**
  * Return 1 if the key exists in the data store, 0 otherwise
  **/
299
BELLESIP_EXPORT int belle_sip_object_data_exists( const belle_sip_object_t *obj, const char* name );
300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332

/**
  * Destroys the named data associated by the name provided.
  *
  * Returns 0 for success, -1 for error
  **/
BELLESIP_EXPORT int   belle_sip_object_data_remove( belle_sip_object_t *obj, const char* name);

/**
  * Retrieve the data from the data store and removes it from the data store, without calling the destructor.
  * This transfers ownership of the data to the caller, which will be in charge of releasing it.
  **/
BELLESIP_EXPORT void* belle_sip_object_data_grab( belle_sip_object_t* obj, const char* name);

/**
  * Clears all data in the object's storage, invoking the destroy_func when possible
  **/
BELLESIP_EXPORT void belle_sip_object_data_clear( belle_sip_object_t* obj );

/**
  * clones the object's data store to another one, using the provided clone function to clone individual data items.
  *
  * The destination data store will be cleaned before pushing the source data into it.
  * For a merge, use #belle_sip_object_data_merge.
  * This is equivalent to the following code:
  *    {
  *     belle_sip_object_data_clear(dst);
  *     belle_sip_object_data_merge(src, dst, clone_func);
  *    }
  *
  * Note that providing NULL as a cloning function will simply assign the src object's data to the dst object.
  *
  **/
333
BELLESIP_EXPORT void belle_sip_object_data_clone( const belle_sip_object_t* src, belle_sip_object_t* dst, belle_sip_data_clone clone_func);
334 335 336 337 338 339 340

/**
  * Merge the source data store into the destination data store.
  *
  * Same function as #belle_sip_object_data_clone, except the destination data store is not cleared before inserting the source data.
  * This overwrites common keys, and keeps existing keys.
  */
341
BELLESIP_EXPORT void belle_sip_object_data_merge( const belle_sip_object_t* src, belle_sip_object_t* dst, belle_sip_data_clone clone_func);
342

343 344 345 346
/**
  * Apply a function for each entry in the data store
  */
BELLESIP_EXPORT void belle_sip_object_data_foreach( const belle_sip_object_t* obj, void (*apply_func)(const char* key, void* data, void* userdata), void* userdata);
Simon Morlat's avatar
Simon Morlat committed
347 348 349 350 351 352 353 354
/**
 * 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.
**/
355
BELLESIP_EXPORT char *belle_sip_object_describe_type_from_name(const char *name);
Simon Morlat's avatar
Simon Morlat committed
356

357
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
358

359 360 361 362 363
/**
 * 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().
**/
364
BELLESIP_EXPORT char* belle_sip_object_to_string(void* obj);
Simon Morlat's avatar
Simon Morlat committed
365

366 367 368 369
/**
 * 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.
**/
370
BELLESIP_EXPORT belle_sip_error_code belle_sip_object_marshal(belle_sip_object_t* obj, char* buff, size_t buff_size, size_t *offset);
Simon Morlat's avatar
Simon Morlat committed
371

372 373
/* use BELLE_SIP_OBJECT_IS_INSTANCE_OF macro(), this function is for use by the macro only*/
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
374 375 376 377 378 379

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)
380 381
#define BELLE_SIP_OBJECT_IS_INSTANCE_OF(obj,_type) _belle_sip_object_is_instance_of((belle_sip_object_t*)obj,_type##_id)

382 383
#define BELLE_SIP_OBJECT_VPTR(obj,object_type) ((BELLE_SIP_OBJECT_VPTR_TYPE(object_type)*)(((belle_sip_object_t*)obj)->vptr))

384 385 386
/*deprecated*/
#define BELLE_SIP_IS_INSTANCE_OF(obj,_type)	BELLE_SIP_OBJECT_IS_INSTANCE_OF(obj,_type)

Simon Morlat's avatar
Simon Morlat committed
387 388 389 390 391 392 393 394 395 396 397 398 399
#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

400
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
401 402 403 404 405 406 407 408 409 410

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__))

411 412
#define BELLE_SIP_IMPLEMENTS(obj,_iface)		belle_sip_object_implements((belle_sip_object_t*)obj,_iface##_id)

Simon Morlat's avatar
Simon Morlat committed
413 414 415 416 417 418 419 420 421 422 423

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;\
424

Simon Morlat's avatar
Simon Morlat committed
425 426 427

#define BELLE_SIP_DECLARE_INTERFACE_END };

428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453
#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 \
	}


454 455 456 457
/**
 * Object holding unowned objects - used as a kind of garbage collector for temporary objects.
**/
typedef struct belle_sip_object_pool belle_sip_object_pool_t;
458

459 460
BELLE_SIP_BEGIN_DECLS

461 462 463 464
/**
 * Push a new object pool for use for creation of new objects.
 * When no longer needed, this pool can be destroyed with belle_sip_object_unref().
**/
Sylvain Berfini's avatar
Sylvain Berfini committed
465
BELLESIP_EXPORT belle_sip_object_pool_t * belle_sip_object_pool_push(void);
466

467
belle_sip_object_pool_t * belle_sip_object_pool_get_current(void);
468
int belle_sip_object_pool_cleanable(belle_sip_object_pool_t *pool);
469
void belle_sip_object_pool_clean(belle_sip_object_pool_t *obj);
Simon Morlat's avatar
Simon Morlat committed
470

471
BELLE_SIP_DECLARE_VPTR(belle_sip_object_t)
472

473 474
BELLE_SIP_END_DECLS

475 476 477
/**
 * Adding a new type in belle-sip in 5 steps
 * =========================================
478
 *
479 480 481 482 483 484
 * Let's suppose you want to add an object called belle_sip_something_t
 * 1) Declare the type in the enum in belle-sip.h:
 * 	BELLE_SIP_TYPE_ID(belle_sip_something_t)
 * 2) Declare the api of the new object in .h, including a typedef and a cast macro:
 * 	typedef struct belle_sip_something belle_sip_something_t;
 * 	#define BELLE_SIP_SOMETHING(obj)	BELLE_SIP_CAST(obj,belle_sip_something_t)
485
 *
486 487 488
 * 	belle_sip_something_t *belle_sip_something_create(int arg1, int arg2);
 * 	void belle_sip_something_do_cooking(belle_sip_something_t *obj);
 *    Do not add any destructor, belle_sip_object_unref() does it for all objects.
489
 *
490 491 492 493 494 495 496 497 498 499 500 501 502
 * 3) in the c file contaning the object's implementation, define the internal structure for your object.
 *   The first field of the struct must be the parent type.
 * 	struct belle_sip_something{
 * 		belle_sip_object_t base;
 * 		int myint1;
 * 		int myint2;
 * 		char *mychar;
 * 	};
 * 4) still in the C file contaning the object's implementation, define a destructor and all functions of its API:
 *    The destructor must only manage the fields from the type, not the parent.
 * 	static void belle_sip_something_destroy(belle_sip_something_t *obj){
 * 		if (obj->mychar) belle_sip_free(obj->mychar);
 * 	}
503
 *
504 505 506 507 508 509 510 511 512 513
 * 	belle_sip_something_t *belle_sip_something_create(int arg1, int arg2){
 * 		belle_sip_something_t *obj=belle_sip_object_new(belle_sip_something_t);
 * 		obj->myint1=arg1;
 * 		obj->myint2=arg2;
 * 		obj->mychar=belle_sip_strdup("Hello world");
 * 		return obj;
 * 	}
 *    Declare the interfaces implemented by the object (to be documented) and instanciate its "vptr", necessary for dynamic casting.
 * 	BELLE_SIP_DECLARE_NO_IMPLEMENTED_INTERFACES(belle_sip_something_t);
 * 	BELLE_SIP_INSTANCIATE_VPTR(belle_sip_something_t, belle_sip_object_t,belle_sip_something_destroy, NULL, NULL,FALSE);
514
 *
515 516 517 518
 * 5) in .h file included everywhere in the source (typically belle_sip_internal.h), declare the vptr
 * 	BELLE_SIP_DECLARE_VPTR(belle_sip_dns_srv_t);
 */

519 520
#if defined(__cplusplus) && defined(BELLE_SIP_USE_STL)
#include <ostream>
521 522
inline   std::ostream&
operator<<( std::ostream& __os, const belle_sip_object_t* object)
523 524 525 526 527 528 529
{
	char* object_as_string = belle_sip_object_to_string((void*)object);
	__os << object_as_string;
	belle_sip_free(object_as_string);
	return __os;
}
#endif
Simon Morlat's avatar
Simon Morlat committed
530 531
#endif