$Id: README,v 1.5.2.1 2003/03/28 05:25:50 bko Exp $

For information about licensing, please see the LICENSE file in this
directory, or http://www.vovida.org/license.html .


Vovida MGCP API README

Introduction

The current version of this MGCP library is intended to implement
RFC2705 Media Gateway Control Protocol (MGCP) Version 1.0 from October 1999.


ARCHITECTURE

The MGCP stack has a class for each MGCP command (e.g. Request
Notification, Delete Connection, etc.).  The message sender creates an
object, and calls methods of that object to set the various possible
parameters.

When the other side receives the message, an object is generated and
passed to the receiving process.  The process can use methods to
examine the contents of the message.

The stack has API support for both blocking and non-blocking sends --
the blocking sends block until the other side successfully responds or
until a time out has occured.

IMPLEMENTATION

The stack is implemented as a two-level stack -- the upper layer is
the externally callable API, while the lowlevel code builds, parses,
and encodes the messages.  More information about it is in the
lowlevel/README file.

MEMORY MANAGEMENT

The application may instantiate a command either on the stack or on the
heap. The stack will make a copy of the object, so it's the application's
responsibility to manage the memory of the original object.

The application sets up the message using methods of the message
object, then passes it to the transport object.

On the receiving side, the stack will create a new message on the
heap, and pass back a pointer to that message. The application does not
need to explicitly free the memory for that object, but will need to delete
all references to that object when done.

ERROR HANDLING

At the moment, error handling is very preliminary.  The intent will be
that error handling will occur by exceptions (in the C++) or error
code returning (in the C), but the exact mechanism is not yet defined
(one known factor is that some C++ compilers and Operating System
combinations deal poorly with exceptions).  We will probably be
changing the API to more clearly define how the error handling will be
done.

INTEROPERABILITY

Some degree of interoperability testing has been performed with this version of
the code, e.g. with Telogy, Cisco 2600 and Audiocodes.

We intend to perform more interoperability testing of the code as
opportunities to do so become available.


DOCUMENTATION

Reference documentation is provided by the Doc++ tool, which allows
developers to place comments in the code and generate HTML / LaTeX and
a class heirarchy of the code.  As it is, a copy of the generated
information is in mgcp/libmgcp/html directory.


ISSUES


The following are (more) known issues with the MGCP implementation:


Completeness:

While the majority of the API is ready and working, a number of things
are missing, including

	Some package items which take arguments (e.g. adsi, much of script)
	Robust and complete error handling

Refer to the TODO file in the upper level for a list of items that are
not completed.


Simplicity:

A number of interfaces which users do not need to be called by users
are exposed to the user.  This may well go away.


Memory:

We saw memory corruption related to string library in multithreaded environment
during high volumes of traffic through the stack, mainly in parseMessage() function.


Efficiency:

Too many gratuitous copies.  There are numerous extra copies in the
code, as well as too much dynamic resizing of templates and the like.
At the very least, the "encode()" functions should pass back char* if
possible, and the results can be merely concatenated together as late
as possible before the send().

I believe this will be reasonably safe in most instances because the
buffers will not be written by more than 1 function.

Implementing a simpler int to char* would also be good.

Another significant time savings can be made by parsing the buffer in
place.  As it is, the parsing code makes several copies of each
sub-portion of an incoming message as it tokenizes each piece of the
message.  A significant savings in copying time would be to scan the
buffer linearly and not copy.  The messages should be able to be
broken down into tokens in a single pass scan.  Even more efficent
would be to scan and tokenize in a single pass, but that might add
complexity to the code.

However, there is also the "premature optimization" argument -- this
should probably be done at a later time when we can actually measure
the code for its performance.


Comments:

The code is not as well commented as it should be.  This will improve.


Build:

Inline functions are not cleanly separated out from the actual headers.

There are a number of warnings in the code.

Name spaces aren't used, but if we use them, then they may break older
versions of gcc.

Not enough uses of assert().
======================================================================

Copyright 2000-2003, Cisco Systems, Inc.
THE INFORMATION HEREIN IS PROVIDED ON AN "AS IS" BASIS, WITHOUT ANY
WARRANTIES OR REPRESENTATIONS, EXPRESS, IMPLIED OR STATUTORY, INCLUDING
WITHOUT LIMITATION, WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.

$Id: README,v 1.5.2.1 2003/03/28 05:25:50 bko Exp $
