SU module handles abstraction to OS specific functionality such as memory management, sockets, threads and time functions. In the media side, AD module abstracts audio device driver implementations.
The following ANSI C 99 features shall not be used in Sofia-SIP software:
Nevertheless its OK to use native integer types if you bear in mind what was said above. The original reason for having only native data type was performance. The int type is always stored in the fastest (and usually biggest size) possible.
Never assume anything on the length of the type. Alway use sizeof() operator to find out the length.
C 99 standard defines the following fixed length data types:
To use these data types you must include the <su_types.h> header, which takes care of including correct file. If su includes are not available, you must include the following code segment to each file where you plan to use them:
#if HAVE_STDINT_H #include <stdint.h> #elif HAVE_INTTYPES_H #include <inttypes.h> #elif SU_HAVE_WIN32 #include <su_types.h> #else #error Define HAVE_STDINT_H as 1 if you have <stdint.h>, \ or HAVE_INTTYPES_H if you have <inttypes.h> #endif
If you wish to convert the byte order, it is simply done by calling one the following functions:
The htonl() function converts the unsigned integer hostlong from host byte order to network byte order.
The htons() function converts the unsigned short integer hostshort from host byte order to network byte order.
The ntohl() function converts the unsigned integer netlong from network byte order to host byte order.
The ntohs() function converts the unsigned short integer netshort from network byte order to host byte order.
You need to include <netinet/in.h> or <su.h> to use these functions.
To tell the compiler that you only need certain amount of bits to store a variable, you can use bit-fields. Compiler may or may not pack the bit-fields.
struct foo { unsigned bar:5; unsigned foo:2; unsigned :0; int something; }
If compiler decides to pack this structure, this code generates a structure that has bar and foo in the first seven bits, and then something beginning from the next 32 bit boundary.
One problem arises when using packed bit-fields: on ARM it is generally not possible to access a 32 bit field that does not start from the 32-bit boundary. Hence the example has the :0 padding member in the structure. Seems handy but beware: initialization of this structure fails on some ARM gcc compilers. (Ask Kai Vehmanen for details).
A way to force packing of a structure is to use preprocessor directive #pragma(pack)
. This directive is compiler specific, so if you plan to write truly portable code, you cannot use it. We have used it in some parts of the Sofia-SIP though. Only alternative is to write functions that fetch the desired bits from a 32 bit field with bit operations; not very handy and error prone.
The same aligment problem also arises if you cast for example char buffer to a int32_t. You can only read int32_t from the 32bit boundary on ARM platform. So be careful.
As a conclusion, when using bit-fields and stucture packing, beware of the pitfalls. If you don't really need to use them (as in parsing binary protocols), don't use them.
In case you like to start developing a new module, please contact Sofia-SIP development team so that they can help you to set up the basic module for you.
An overview of the contents of a module directory:
How to implement data hiding in C? Easiest answer is to only declare data structures in the header files, not to define them. We have a typedef msg_t for struct msg_s in <msg.h>, but the actual structure is defined in <msg_internal.h>. Programs outside msg module does not have access to the struct msg_s , but they have to to access the msg_t object through method functions provided in <msg.h>. The msg implementation is also free to change the internal layout of the structure, only keeping the function interface unmodified.
Abstract interface is achieved using virtual function table, just as C++ typically implements abstract classes and virtual functions. Each codec defines a structure containing functions implementing the interface, and returns a pointer to the structure within a codec instance.
In this sence, inheritance means that a pointer to a derived object can be casted as a pointer to a base object. In other words, the derived object must have the base object at the beginning of its memory area:
struct derived { struct base base[1]; int extra; char *data; };
There are three alternatives to cast a pointer to derived to a pointer to base:
struct base *base1 = (struct base *)derived; struct base *base2 = &derived->base; struct base *base3 = derived->base;
See documentation of <su_alloc.h> and memory managment tutorial for more information of memory management services.
/* context info structure */ struct context { su_home_t ctx_home[1]; /* memory home */ other_t *ctx_other_stuff; /* example of memory areas */ ... }; /* context pointer */ struct context *ctx; /* Allocate memory for context structure and initialize memory home */ ctx = su_home_clone(NULL, sizeof (struct context)); /* Allocate memory and register it with memory home */ ctx->ctx_other_stuff = su_zalloc(ctx->ctx_home, sizeof(other_t)); ... processing and allocating more memory ... /* Release registered memory areas, home, and context structure */ su_home_zap(ctx->ctx_home);
/* example sub-procedure. top_home is upper-level memory home */ int sub_procedure( su_home_t *top_home, ... ) { su_home_t temphome[1] = { SU_HOME_INIT(temphome) }; ... allocations and other processing ... /* was processing successfull ? */ if (success) { /* ok -> move registered allocated memory to upper level memory home */ su_home_move( top_home, temphome ); } /* destroy temporary memory home (and registered allocations) */ /* Note than in case processing was succesfull the memory */ /* registrations were already moved to upper level home. */ su_home_deinit(temphome); /* return ok/not-ok */ return success; }
Here are some ideas of what you should test:
TESTS = my_test_foo my_test_bar check_PROGRAMS = my_test_foo my_test_bar my_test_foo_SOURCES = foo.c foo.h my_test_foo_LDADD = -L. -lmy my_test_bar_SOURCES = bar.c bar.h my_test_foo_LDADD = -L. -lmy
Each test program should either return zero for success or a non-zero error code in its main function. Now when you run "make check", my_test_foo and my_test_bar will be built and then run. Make will print a summary of how the tests went. As these tests are run from the build system, the tests must be non-interactive (no questions asked) and not rely on any files that are not in CVS.
Sofia-SIP's top-level makefile contains a recursive check target, so you can use "cd sofia ; make check" to run all the existing tests with a single command.
A good introduction to these tools is available at developer.gnome.org. Autobook provides more detailed documentation for autoconf and automake. The GNU make manual is also a good source of information.
This file is created by the developer of the module.
Contact Sofia-SIP development team, if you need changes to these files.
This file is generated by aclocal command.
This file is created by the developer of the module.
@FOO@
variables in the source *.in files are replaced with values found during the configuration process. For instance the variable @srcdir@
in Makefile.in is replaced in Makefile with the source directory path (useful when compiling outside the main source tree).This file is generated by autoconf command.
This file is generated by configure command.
This file is generated by configure command.
make
program. Makefile is generated from Makefile.in when you run autoconf
command. Ensure that "make dist" and "make install" targets work.This file is generated by configure command (via config.status).
This file is generated by configure command.