\input texinfo   @c -*-texinfo-*-
@setfilename scscp.info

@set LIBRARYNAME SCSCP C Library
@set LIBRARYCNAME  C
@set LIBRARYCXXNAME  C++
@set LIBRARYSHORTNAME SCSCP
@documentlanguage en
@settitle SCSCP C Library 

@include version.texi

@c %-------------------------------------------------------------
@c macros for this file
@set emailreportbugs @email{gastineau@@imcce.fr}
@set scscpurl @url{http://www.imcce.fr/trip/scscp/}
@set statusignoremessage @code{SCSCP_STATUS_IGNORE} could be used for @var{status} in order to ignore the returned value.
@set funcfails On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.


@macro  paramid 
@var{id} is the id of this object for the future reference (see OMR). @var{id} could be NULL if unset.
@end macro

@macro funcfailssetstatus{param1}
     On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If @code{\param1\ } fails, the value of @var{status} is set to the corresponding error value.
@end macro
@macro funcfailsptrsetstatus{param1}
     On exit, it returns @code{NULL} if an error occurs, otherwise the return value is a valid address. If @code{\param1\ } fails, the value of @var{status} is set to the corresponding error value.
@end macro
@macro funcfailsxmlreadOM{param1}
     On exit, it returns 0 if @var{node} doesn't contain \param1\ , otherwise the return value is a non-zero value.
@end macro
@macro funcxxfailssetstatus{param1}
     On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
@end macro
@macro funcxxfailsnoexcept{param1}
     On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
@end macro
@macro funcstreamxxfailssetstatus{param1}
     On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
@end macro
@c %-------------------------------------------------------------


@c  The following two commands
@c  start the copyright page.
@copying
Copyright @copyright{} 2008, 2009, 2010, 2011, 2012
M. Gastineau, Astronomie et Syst@`emes Dynamiques, IMCCE, CNRS, Observatoire de Paris

gastineau@@imcce.fr


This library is governed by the CeCILL-C or CeCILL license under French law and
abiding by the rules of distribution of free software.  You can  use, 
modify and/ or redistribute the software under the terms of the CeCILL-C
license as circulated by CEA, CNRS and INRIA at the following URL
"http://www.cecill.info". 

As a counterpart to the access to the source code and  rights to copy,
modify and redistribute granted by the license, users are provided only
with a limited warranty  and the software's author,  the holder of the
economic rights,  and the successive licensors  have only  limited
liability. 

In this respect, the user's attention is drawn to the risks associated
with loading,  using,  modifying and/or developing or reproducing the
software by the user in light of its specific status of free software,
that may mean  that it is complicated to manipulate,  and  that  also
therefore means  that it is reserved for developers  and  experienced
professionals having in-depth computer knowledge. Users are therefore
encouraged to load and test the software's suitability as regards their
requirements in conditions enabling the security of their systems and/or 
data to be ensured and,  more generally, to use and operate it in the 
same conditions as regards security. 

The fact that you are presently reading this means that you have had
knowledge of the CeCILL-C or CeCILL license and that you accept its terms.
@end copying

@titlepage

@title @value{LIBRARYNAME}
@subtitle Reference manual
@subtitle version @value{VERSION}
@subtitle @value{UPDATED}
@author M. Gastineau
@email{gastineau@@imcce.fr}

@iftex
@page
@vskip 0pt plus 1filll
@end iftex

This manual documents how to install and use the @value{LIBRARYNAME}, version @value{VERSION}.

Copyright @copyright{} 2008, 2009, 2010, 2011, 2012

M. Gastineau, Astronomie et Syst@`emes Dynamiques, IMCCE, CNRS, Observatoire de Paris

@email{gastineau@@imcce.fr}
@end titlepage

@documentdescription
How to install and use the @value{LIBRARYNAME}, version @value{VERSION}.
@end documentdescription

@contents

@node Top, @value{LIBRARYNAME} Copying conditions, , (dir)
@top @value{LIBRARYNAME}

@menu
* @value{LIBRARYNAME} Copying conditions ::
* Introduction to @value{LIBRARYNAME} ::
* Installing @value{LIBRARYNAME} ::
* Reporting bugs ::
* @value{LIBRARYNAME} Basics ::
* @value{LIBRARYCNAME} Interface ::
* Design a SCSCP C server ::
* Design a SCSCP C client ::
* @value{LIBRARYCXXNAME} Interface ::
* Design a SCSCP C++ server ::
* Design a SCSCP C++ client ::
* References ::
@end menu

@node @value{LIBRARYNAME} Copying conditions, Introduction to @value{LIBRARYNAME}, Top, Top
@chapter @value{LIBRARYNAME} Copying conditions
@insertcopying


@c %----------------------------------------------------------------------------
@c %----------------------------------------------------------------------------
@node Introduction to @value{LIBRARYNAME}, Installing @value{LIBRARYNAME},@value{LIBRARYNAME} Copying conditions, Top
@chapter Introduction to @value{LIBRARYNAME}


This library is an implementation of the  Symbolic Computation Software 
Composibility Protocol (SCSCP). The current implementation is based on the specification version 1.3 (@pxref{References}).

This library provides API to develop client applications to access Computer Algebra Systems which support that protocol. So these client applications will be refered as @samp{SCSCP client} in this documentation.

Computer Algebra Systems could use the API to provide services to other applications using this protocol. So these Computer Algebra Systems will be refered as @samp{SCSCP server} in this documentation.
 
This library provides a C and C++ API to allow to be used in C or C++ programs.


@c %----------------------------------------------------------------------------
@c %----------------------------------------------------------------------------
@node Installing @value{LIBRARYNAME},Reporting bugs,Introduction to @value{LIBRARYNAME}, Top
@chapter Installing @value{LIBRARYNAME}


@section Installation on a Unix-like system (Linux, Mac OS X, BSD, cygwin, ...)
To build @value{LIBRARYNAME}, you first have to install Libxml2 version 2.6 or later (see @url{http://xmlsoft.org/}) on your computer.  You need C and C++ compilers, such as gcc and g++. And you need a standard Unix @samp{make} program, plus some other standard Unix utility
programs.

Here are the steps needed to install the library on Unix systems:

@enumerate
@item
@samp{tar xzf scscp-@value{VERSION}.tar.gz}

@item
@samp{cd scscp-@value{VERSION}}

@item
@samp{./configure}

Running @command{configure} might take a while.  While running, it prints some
messages telling which features it is checking for.

@command{configure} recognizes the following options to control how it
operates.

@table @option
@item --help
@itemx -h
Print a summary of all of the options to @command{configure}, and exit.

@item --prefix=@var{dir}
Use @var{dir} as the installation prefix.  See the command @command{make install} for the installation names.
@end table

@item
@samp{make}

This compiles @value{LIBRARYNAME} in the working directory.

@item
@samp{make check}

This will make sure @value{LIBRARYNAME} was built correctly.

If you get error messages, please report them to
@value{emailreportbugs} (@xref{Reporting bugs}, for
information on what to include in useful bug reports).

@item
@samp{make install}

This will copy the files @file{scscp.h}, @file{scscpxx.h} and @file{scscptypes.h} to the directory
@file{/usr/local/include}, the files @file{libscscp.a} and @file{libscscpxx.a} to the directory
@file{/usr/local/lib}, and the file @file{scscp.info} to the directory
@file{/usr/local/share/info} (or if you passed the @samp{--prefix} option to
@file{configure}, using the prefix directory given as argument to
@samp{--prefix} instead of @file{/usr/local}). Note: you need write permissions
on these directories.

@end enumerate


@subsection Other `make' Targets

There are some other useful make targets:

@itemize @bullet
@item
@samp{scscp.info} or @samp{info}

Create an info version of the manual, in @file{scscp.info}.

@item
@samp{scscp.pdf} or @samp{pdf}

Create a PDF version of the manual, in @file{scscp.pdf}.

@item
@samp{scscp.dvi} or @samp{dvi}

Create a DVI version of the manual, in @file{scscp.dvi}.

@item
@samp{scscp.ps} or @samp{ps}

Create a Postscript version of the manual, in @file{scscp.ps}.

@item
@samp{scscp.html} or @samp{html}

Create an HTML version of the manual, in several pages in the directory
@file{scscp.html}; if you want only one output HTML file, then type
@samp{makeinfo --html --no-split scscp.texi} instead.

@item
@samp{clean}

Delete all object files and archive files, but not the configuration files.

@item
@samp{distclean}

Delete all files not included in the distribution.

@item
@samp{uninstall}

Delete all files copied by @samp{make install}.
@end itemize


@section Installation on Windows system
To build @value{LIBRARYNAME}, you first have to install Libxml2 version 2.6 or later (see @url{http://xmlsoft.org/}) on your computer.  You need C and C++ compilers and a Windows SDK. It has been successfully compiled with  the Windows Server 2003 R2 Platform SDK,
the Windows SDK of Vista, and the Windows Server 2008 Platform SDK. 

Here are the steps needed to install the library on Windows systems:

@enumerate
@item
Expand the file @samp{scscp-@value{VERSION}.tar.gz}

@item Execute the command @samp{cmd.exe} from the menu @samp{Start} / @samp{Execute...}

This will open a console window

@item
@samp{cd }@var{dir}@samp{\scscp-@value{VERSION}}

Go to the directory @var{dir} where @value{LIBRARYNAME} has been expanded.

@item
@samp{nmake /f makefile.vc XMLDIR=@var{dir}}

This compiles @value{LIBRARYNAME} in the working directory.
Use @var{dir} as the installation directory of the libxml2 library. 

@item
@samp{nmake /f makefile.vc XMLDIR=@var{dir} check}

This will make sure @value{LIBRARYNAME} was built correctly.

If you get error messages, please report them to
@value{emailreportbugs} (@xref{Reporting bugs}, for
information on what to include in useful bug reports).

@item
@samp{nmake /f makefile.vc  install DESTDIR=@var{dir}}

This will copy the files @file{scscp.h}, @file{scscpxx.h} and @file{scscptypes.h} to the directory
@var{dir}@file{\include}, the files @file{scscp.lib} and @file{scscpxx.lib} to the directory
@var{dir}@file{\lib}, the file @file{scscp.info} and @file{scscp.pdf} to the directory @var{dir}@file{\doc}. Note: you need write permissions on these directories.

@end enumerate


@c %----------------------------------------------------------------------------
@c %----------------------------------------------------------------------------
@node Reporting bugs, @value{LIBRARYNAME} Basics, Installing @value{LIBRARYNAME}, Top
@chapter Reporting bugs


@sp 1
If you think you have found a bug in the @value{LIBRARYNAME}, first have a look on the @value{LIBRARYNAME} web page @value{scscpurl} , in which case you may find there a workaround for it. Otherwise, please investigate and report it. We have made this library available to you, and it is not to ask too much from you, to ask you to report the bugs that you find.

@sp 1
There are a few things you should think about when you put your bug report together.
You have to send us a test case that makes it possible for us to reproduce the bug. Include instructions on how to run the test case.

@sp 1
You also have to explain what is wrong; if you get a crash, or if the results printed are incorrect and in that case, in what way.

@sp 1
Please include compiler version information in your bug report. This can be extracted using @samp{cc -V} on some machines, or, if you're using gcc, @samp{gcc -v}. Also, include the output from @samp{uname -a} and the @value{LIBRARYSHORTNAME} version.

@sp 1
Send your bug report to: @value{emailreportbugs}.
If you think something in this manual is unclear, or downright incorrect, or if the language needs to be improved, please send a note to the same address.

@c %----------------------------------------------------------------------------
@c %----------------------------------------------------------------------------
@node @value{LIBRARYNAME} Basics, @value{LIBRARYCNAME} Interface, Reporting bugs, Top
@chapter @value{LIBRARYNAME} Basics
@c %----------------------------------------------------------------------------
@section Headers and Libraries


All C declarations needed to use C interface are collected in the include file @file{scscp.h}.  It is designed to work with both C and C++ compilers. All C++ declarations needed to use C++ interface are collected in the include file @file{scscpxx.h}.

You should include that file in any C program using the @value{LIBRARYNAME} :

@example
#include <scscp.h>
@end example

You should include that file in any C++ program using the @value{LIBRARYNAME} :

@example
#include <scscpxx.h>
@end example

   Note however that the @value{LIBRARYSHORTNAME} constants use @code{NULL}, the header file @file{stdio.h} must be included before.

@example
     #include <stdio.h>
     #include <scscp.h>
@end example

   
@subsection Compilation on a Unix-like system
 
 All C programs using  @value{LIBRARYSHORTNAME} must link against the @file{libscscp} library and the Libxml2 library.  On Unix-like system this can be done with @option{-lscscp `xml2-config --libs`}, for example

@example
     gcc myprogram.c -o myprogram -lscscp `xml2-config --libs`
@end example

@sp 1
 All C++ programs using  @value{LIBRARYSHORTNAME} must link against the @file{libscscpxx} and @file{libscscp} libraries and the Libxml2 library.  On Unix-like system this can be done with @option{-lscscpxx -lscscp `xml2-config --libs`}, for example

@example
   g++ myprogram.cpp -o myprogram -lscscpxx -lscscp `xml2-config --libs`
@end example


@sp 1
   If  @value{LIBRARYNAME} has been installed to a non-standard location then it may be necessary to use @option{-I} and @option{-L} compiler options to point to the right directories, and some sort of run-time path for a shared library.

@subsection Compilation on a Windows system
 
 All C programs using @value{LIBRARYSHORTNAME} must link against the @file{scscp.lib} library and the Libxml2 library. On Windows system this can be done with @option{scscp.lib libxml2_a.lib iconv.lib wsock32.lib ws2_32.lib}, for example

@example
cl.exe /out:myprogram myprogram.c scscp.lib libxml2_a.lib iconv.lib \
                                  wsock32.lib ws2_32.lib
@end example

@sp 1
 All C++ programs using @value{LIBRARYSHORTNAME} must link against the @file{scscpxx.lib} and @file{scscp.lib} libraries and the Libxml2 library. 
 
 On Windows system this can be done with @option{scscpxx.lib scscp.lib libxml2_a.lib iconv.lib wsock32.lib ws2_32.lib}, for example

@example
cl.exe /out:myprogram myprogram.cpp scscpxx.lib scscp.lib \
                       libxml2_a.lib iconv.lib  wsock32.lib ws2_32.lib
@end example


@sp 1
 If  @value{LIBRARYNAME} has been installed to a non-standard location then it may be necessary to use @option{/I} and @option{/LIBPATH:} compiler options to point to the right directories.


@c %----------------------------------------------------------------------------
@section Thread safe

@value{LIBRARYNAME} is reentrant and thread-safe wit some exceptions:

@enumerate
@item  It's safe for two threads to read from the same @value{LIBRARYSHORTNAME} variable simultaneously, but it's not safe for one to read while the another might be writing, nor for two threads to write simultaneously.

@item If the standard I/O functions such as @code{send} are not reentrant
     then the @value{LIBRARYSHORTNAME} I/O functions using them will not be reentrant either.
@end enumerate

@c %----------------------------------------------------------------------------
@c %----------------------------------------------------------------------------
@node @value{LIBRARYCNAME} Interface,  Design a SCSCP C server, @value{LIBRARYNAME} Basics, Top
@chapter @value{LIBRARYCNAME} Interface

@menu
* Constants ::
* Types ::
* Server functions ::
* Client functions ::
* I/O functions ::
* Status functions ::
* Procedure call options functions ::
* Procedure return options functions  ::
* XML parsing functions ::
* Remote objects functions ::
* Miscellaneous functions ::
@end menu

@c %----------------------------------------------------------------------------
@node Constants, Types,, @value{LIBRARYCNAME} Interface
@section Constants

SCSCP_VERSION_MAJOR

This integer constant defines the major revision of this library. It can be used to distinguish different releases of this library.


SCSCP_VERSION_MINOR

This integer constant defines the minor revision of this library. It can be used to distinguish different releases of this library.

SCSCP_VERSION_PATCH

This integer constant defines the patch level revision of this library. It can be used to distinguish different releases of this library.

@cartouche
@example

#if   (SCSCP_VERSION_MAJOR>=2) 
  ||  (SCSCP_VERSION_MAJOR>=1 && SCSCP_VERSION_MINOR>=3)
...
#endif
@end example
@end cartouche

SCSCP_PROTOCOL_VERSION_1_3

This string defines the version string for the SCSCP specification version 1.3 .

SCSCP_PROTOCOL_VERSION_1_2

This string defines the version string for the SCSCP specification version 1.2 .

SCSCP_PROTOCOL_DEFAULTPORT 

This integer is the default value on which port should listen the SCSCP server.  The value 26133 for this port has been assigned to SCSCP by the Internet Assigned Numbers Authority (IANA) in November 2007, see http://www.iana.org/assignments/port-numbers. 

@c %----------------------------------------------------------------------------
@node Types, Server functions ,Constants, @value{LIBRARYCNAME} Interface
@section Types

@menu
* SCSCP_socketserver ::
* SCSCP_socketclient ::
* SCSCP_incomingclient ::
* SCSCP_status ::
* SCSCP_calloptions ::
* SCSCP_returnoptions ::
* SCSCP_msgtype ::
* SCSCP_encodingtype ::
* SCSCP_xmlnodeptr ::
* SCSCP_xmlattrptr ::
* SCSCP_io ::
@end menu

@node SCSCP_socketserver, SCSCP_socketclient, , Types
@subsection SCSCP_socketserver

@deftp {Data type} SCSCP_socketserver

This type contains all information of the SCSCP server.

Before using any object of this type, the function @code{SCSCP_ss_init} must be called. @c % (@pxref{SCSCP_ss_init}).

@end deftp

@node SCSCP_socketclient, SCSCP_incomingclient, SCSCP_socketserver, Types
@subsection SCSCP_socketclient

@deftp {Data type} SCSCP_socketclient

This type contains all information of the SCSCP client about the connection through a socket to a SCSCP server.

Before using any object of this type, the function @code{SCSCP_sc_init} must be called. @c % (@pxref{SCSCP_sc_init}).

@end deftp

@node SCSCP_incomingclient, SCSCP_status, SCSCP_socketclient, Types
@subsection SCSCP_incomingclient

@deftp {Data type} SCSCP_incomingclient

This type contains all information of an incoming connection accepted by a server.

@end deftp

@node SCSCP_status, SCSCP_calloptions, SCSCP_incomingclient, Types
@subsection SCSCP_status

@deftp {Data type} SCSCP_status

This type contains all information about errors. Before using any object of this type, the @code{SCSCP_STATUS_INITIALIZER} must be used to initialize the status object.

@cartouche
@example
 SCSCP_status status = SCSCP_STATUS_INITIALIZER;
 ...
@end example
@end cartouche

 Each function of the library updates an object of this type if an error occurs during the processing. The value @code{SCSCP_STATUS_IGNORE} could be used in order to ignore the returned value by these functions.
 
The possible values are
@table @samp
@item SCSCP_STATUS_OK
No error occurs.

@item SCSCP_STATUS_ERRNO
The variable errno is set to a system error. The value of errno specifies the error.

@item SCSCP_STATUS_EXECFAILED
The remote execution fails.

@item SCSCP_STATUS_NOMEM
Not enough memory

@item SCSCP_STATUS_OPENMATHNOTVALID 
The OpenMath expression isn't valid.

@item SCSCP_STATUS_RECVCANCEL
The interrupt message "<? scscp cancel ?>" was received.

@item SCSCP_STATUS_RECVQUIT
The quit message "<? scscp quit ?>" was received or the socket is closed before receiving this message.

@item SCSCP_STATUS_USAGEUNKNOWNDEBUGLEVEL
The debug level isn't available in the procedure call message.

@item SCSCP_STATUS_USAGEUNKNOWNMEM
The memory usage isn't available in the procedure return message.

@item SCSCP_STATUS_USAGEUNKNOWNMESSAGE
The information message isn't available in the procedure return message.

@item SCSCP_STATUS_USAGEUNKNOWNMINMEMORY
The minimal memory isn't available in the procedure call message.

@item SCSCP_STATUS_USAGEUNKNOWNMAXMEMORY
The maximal memory isn't available in the procedure call message.

@item SCSCP_STATUS_USAGEUNKNOWNRETURNTYPE
The return type isn't available in the procedure call message

@item SCSCP_STATUS_USAGEUNKNOWNRUNTIME
The runtime usage isn't available in the procedure return message.

@item SCSCP_STATUS_USAGEUNKNOWNRUNTIMELIMIT
The runtime limit usage isn't available in the procedure call message.

@item SCSCP_STATUS_VERSIONNEGOTIATIONFAILED
The version negotiation fails.

@end table

The following values indicate an invalid usage of the library
@table @samp
@item SCSCP_STATUS_CALLIDISNOTSET
The call identifier isn't defined in the options.

@item SCSCP_STATUS_CALLOPTIONSOBJECTNULL
The object call options passed to the function is NULL.

@item SCSCP_STATUS_CLIENTOBJECTNULL
The object client passed to the function is NULL.

@item SCSCP_STATUS_RETURNOPTIONSOBJECTNULL
The object return options passed to the function is NULL.

@item SCSCP_STATUS_RETURNTYPEISNOTSET
The return type isn't defined in the options.

@item SCSCP_STATUS_SERVEROBJECTNULL
The object server passed to the function is NULL.

@item SCSCP_STATUS_STREAMOBJECTNULL
The object stream passed to the function is NULL.

@end table

@end deftp


@node SCSCP_calloptions, SCSCP_returnoptions, SCSCP_status, Types
@subsection SCSCP_calloptions

@deftp {Data type} SCSCP_calloptions

This type contains all information about the options for a procedure call. 
The attribute of the procedure call could be set using the functions @code{SCSCP_co_set_xxx}. The attribute of the procedure call could be get using the functions @code{SCSCP_co_get_xxx}.


The value @code{SCSCP_CALLOPTIONS_DEFAULT} could be used in order to use the default procedure call options. In this case, a unique call identifier will be generated using the prefix @code{libSCSCP:} and the procedure call will return no value (@code{SCSCP_option_return_nothing} will be used). 

Before using any object of this type, the function @code{SCSCP_co_init} must be called. @c % @pxref{SCSCP_co_init}.

@end deftp



@node SCSCP_returnoptions, SCSCP_msgtype, SCSCP_calloptions, Types
@subsection SCSCP_returnoptions

@deftp {Data type} SCSCP_returnoptions

This type contains all information about the options for a procedure return. 
The attribute of the procedure return could be set using the functions @code{SCSCP_ro_set_xxx}. The attribute of the procedure return could be get using the functions @code{SCSCP_ro_get_xxx}.

The value @code{SCSCP_RETURNOPTIONS_IGNORE} could be used in order to ignore the returned value by the function @code{SCSCP_sc_callrecvheader}, @code{SCSCP_sc_callrecvstr}.
 
Before using any object of this type, the function @code{SCSCP_ro_init} must be called. @c % @pxref{SCSCP_ro_init}.

@end deftp


@node SCSCP_msgtype, SCSCP_encodingtype, SCSCP_returnoptions, Types
@subsection SCSCP_msgtype

@deftp {Data type} SCSCP_msgtype

This type defines the type of sent messages between the client and the server.

The available values are

@table @samp
@item SCSCP_msgtype_ProcedureTerminated 
The message is a "Procedure terminated". It is defined by the symbol @code{procedure_terminated} of the OpenMath Content Dictionary @code{scscp1}.

@item SCSCP_msgtype_ProcedureCompleted 
The message is a "Procedure completed". It is defined by the symbol @code{procedure_completed} of the OpenMath Content Dictionary @code{scscp1}.

@item SCSCP_msgtype_ProcedureCall 
The message is a "Procedure call". It is defined by the symbol @code{procedure_call} of the OpenMath Content Dictionary @code{scscp1}.
 
@item SCSCP_msgtype_Interrupt 
The message is a "Interrupt" signal. It is defined by the processing instruction "<? scscp terminate ?>".
@end table
 
@end deftp


@node SCSCP_encodingtype, SCSCP_xmlnodeptr, SCSCP_msgtype, Types
@subsection SCSCP_encodingtype

@deftp {Data type} SCSCP_encodingtype

This type defines the encoding type of the sent OpenMath Objects between the client and the server.

The available values are

@table @samp
@item SCSCP_encodingtype_XML 
The OpenMath objects are encoded using the XML encoding. It is the default encoding for all connections. 

@item SCSCP_encodingtype_Binary 
The OpenMath objects are encoded using the Binary encoding.
@end table
 
@end deftp

@node SCSCP_xmlnodeptr, SCSCP_xmlattrptr, SCSCP_encodingtype, Types
@subsection SCSCP_xmlnodeptr

@deftp {Data type} SCSCP_xmlnodeptr

This type defines a pointer to a node of a XML tree. 
@end deftp

@node SCSCP_xmlattrptr,SCSCP_io, SCSCP_xmlnodeptr, Types
@subsection SCSCP_xmlattrptr

@deftp {Data type} SCSCP_xmlattrptr

This type defines a pointer to an attribute of a node of type SCSCP_xmlnodeptr  (noode of a XML tree). 
@end deftp

@node SCSCP_io,,SCSCP_xmlattrptr, Types
@subsection SCSCP_io

@deftp {Data type} SCSCP_io

This type defines a pointer to a low-level Input/output stream.
@end deftp

@c %----------------------------------------------------------------------------
@node Server functions , Client functions, Types, @value{LIBRARYCNAME} Interface
@section Server functions

The following functions manage all operations on the @code{SCSCP_socketserver} and @code{SCSCP_incomingclient} objects.


@subsection SCSCP_ss_init

@deftypefn {Library Function} int SCSCP_ss_init
            ( SCSCP_socketserver* @var{server}, SCSCP_status* @var{status} , const char* @var{servicename}, const char* @var{serviceversion}, const char* @var{serviceid}, ...)
@end deftypefn
 
It initializes the internal structure of the object @var{server}. The variadic arguments should be of the type @code{const char*} and the last argument must be @code{NULL}. The variadic parameters define the allowed version of SCSCP protocol that could be negotiated with the SCSCP server. 

The arguments @var{servicename}, @var{serviceversion} and @var{serviceid} are used as the value of the attribute @code{service_name}, @code{service_version} and @code{service_id} of the @i{Connection Initiation Message}.

The constants @code{SCSCP_PROTOCOL_VERSION_x_x} could be used for the variadic  parameters.


@funcfailssetstatus{SCSCP_ss_init} @value{statusignoremessage} 

The following example shows how to initialize the server supporting the scscp versions "1.3" and "1.001" . 
@cartouche
@example
 SCSCP_status status;
 SCSCP_server server;
 int res;
 
 res = SCSCP_ss_init(&server, &status, "MYCAS","1","myid", 
                       SCSCP_PROTOCOL_VERSION_1_3, 
                       "1.001", NULL); 
 @end example
@end cartouche

@c %-----------------------
@subsection SCSCP_ss_clear

@deftypefn {Library Function} int SCSCP_ss_clear ( SCSCP_socketserver* @var{server}, SCSCP_status* @var{status} )
@end deftypefn
 
It clears  the internal structure of the object @var{server} and frees allocated memory for this object by the function @code{SCSCP_ss_init}.

@funcfailssetstatus{SCSCP_ss_clear} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_ss_listen

@deftypefn {Library Function} int SCSCP_ss_listen ( SCSCP_socketserver* @var{server}, int @var{port},  int @var{firstavailable}, SCSCP_status* @var{status} )
@end deftypefn
 
@var{server} creates an internal queue for the incoming connections and starts to listen on the @var{port} of "localhost". If the @var{port} isn't available and @var{firstavailable} = 0, it fails. If the @var{port} isn't available and @var{firstavailable} = 1, it retries with the next port until it finds an available port.

@funcfailssetstatus{SCSCP_ss_listen} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_ss_close

@deftypefn {Library Function} int SCSCP_ss_close ( SCSCP_socketserver* @var{server}, SCSCP_status* @var{status} )
@end deftypefn
 
@var{server} terminates to listen for the incoming connections. 

@funcfailssetstatus{SCSCP_ss_close} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_ss_acceptclient

@deftypefn {Library Function} int SCSCP_ss_acceptclient ( SCSCP_socketserver* @var{server}, SCSCP_incomingclient* @var{incomingclient}, SCSCP_status* @var{status} )
@end deftypefn
 
@var{server} extracts the first connection request on the queue of pending connections. If no pending connections are present on the queue, it blocks the caller until a connection is present.

After the @i{Connection Initiation}, the server returns, in the argument @var{incomingclient}, an object to manage future exchanged messages.

After the transactions, @var{incomingclient} must be closed and cleared with the function @code{SCSCP_ss_closeincoming}.

@funcfailssetstatus{SCSCP_ss_acceptclient} @value{statusignoremessage} 

The following example shows how to implement the main loop of the SCSCP server. @cartouche
@example
 SCSCP_status status;
 SCSCP_incomingclient incomingclient;
 SCSCP_server server;

 /*initialization of the server */
 SCSCP_ss_init(&server, &status, "MYCAS","1","myid", 
                     SCSCP_PROTOCOL_VERSION_1_3, 
                     "1.001", NULL); 
               
 SCSCP_ss_listen(&server, SCSCP_PROTOCOL_DEFAULTPORT, &status); 
 
 while (SCSCP_ss_acceptclient(&server, &incomingclient, &status))
 @{
    ... process incoming message ...
   
    SCSCP_ss_closeincoming(&incomingclient, &status);
 @}

 
 /* destroy the server */
 SCSCP_ss_close(& server, &status);
 SCSCP_ss_clear(&server, &status);

@end example
@end cartouche



@c %-----------------------
@subsection SCSCP_ss_closeincoming
@deftypefn {Library Function} int SCSCP_ss_closeincoming ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_status* @var{status})
@end deftypefn

It closes the connection with the client and clears the object @var{incomingclient}.

@funcfailssetstatus{SCSCP_ss_closeincoming} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_ss_callrecvstr
@deftypefn {Library Function} int SCSCP_ss_callrecvstr ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_calloptions* @var{options}, SCSCP_msgtype* @var{msgtype}, char** @var{openmathbuffer}, SCSCP_status* @var{status})
@end deftypefn

It waits for an incoming message. When a new message is available, then it reads the attribute, the type and the content of the message sent by the client @var{incomingclient}. 

The call options @var{options} could be get using the functions @code{SCSCP_co_get_xxx}. @var{options} must be initialized before with the function @code{SCSCP_co_init}.

On exit, the argument @var{msgtype} must be @code{SCSCP_msgtype_ProcedureCall} or @code{SCSCP_msgtype_Interrupt}. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument @var{msgtype} is @code{SCSCP_msgtype_Interrupt}, @var{options} contains the call identifier of the interrupted procedure call.

On exit, the argument @var{openmathbuffer} contains the content of the message sent by the client.  This string must be freed by the system call @code{free}.

@funcfailssetstatus{SCSCP_ss_callrecvstr} @value{statusignoremessage} 



@c %-----------------------
@subsection SCSCP_ss_callrecvheader
@deftypefn {Library Function} int SCSCP_ss_callrecvheader ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_calloptions* @var{options}, SCSCP_msgtype* @var{msgtype}, SCSCP_status* @var{status})
@end deftypefn

It reads the attribute and type of the message sent by the client @var{incomingclient}.

The call options @var{options} could be get using the functions @code{SCSCP_co_get_xxx}. @var{options} must be initialized before with the function @code{SCSCP_co_init}.

On exit, the argument @var{msgtype} must be @code{SCSCP_msgtype_ProcedureCall} or @code{SCSCP_msgtype_Interrupt}. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument @var{msgtype} is @code{SCSCP_msgtype_Interrupt}, @var{options} contains the call identifier of the interrupted procedure call.

@funcfailssetstatus{SCSCP_ss_callrecvheader} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_ss_getxmlnode
@deftypefn {Library Function} SCSCP_xmlnodeptr SCSCP_ss_getxmlnode ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_status* @var{status})
@end deftypefn
This function returns a pointer to the current XML tree received from the client. This function could be used to start parsing the message sent by the client.
This pointer is valid until the next call to the functions @code{SCSCP_ss_callrecv...}.

@funcfailsptrsetstatus{SCSCP_ss_getxmlnode} @value{statusignoremessage} 

@subsection SCSCP_ss_getxmlnoderawstring
@deftypefn {Library Function}  char * SCSCP_ss_getxmlnoderawstring ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_xmlnodeptr @var{curnode}, SCSCP_status* @var{status})
@end deftypefn
This function returns the content of the current node @var{curnode} and its children as a string.
This string must be freed by the system call @code{free}.

@funcfailsptrsetstatus{SCSCP_ss_getxmlnoderawstring} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_ss_sendterminatedstr

@deftypefn {Library Function} int SCSCP_ss_sendterminatedstr ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_returnoptions* @var{options},  const char * @var{cdname}, const char * @var{symbolname}, const char * @var{message}, SCSCP_status* @var{status} )
@end deftypefn

It sends a "procedure terminated" message to the SCSCP client  with the @var{options}. The symbol of the OpenMath Error is defined by  its name @var{symbolname} and its CD @var{cdname}. @var{message} is the message that will be inserted in a OMSTR OpenMath object.

@funcfailssetstatus{SCSCP_ss_sendterminatedstr} @value{statusignoremessage} 

@cartouche
@example
 SCSCP_ss_sendterminatedstr(&incomingclient, &options,
                            "scscp1","error_system_specific", 
                            "can't store a remote object",  &status); 
@end example
@end cartouche

@c %-----------------------
@subsection SCSCP_ss_sendcompletedstr

@deftypefn {Library Function} int SCSCP_ss_sendcompletedstr ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_returnoptions* @var{options},  const char * @var{openmathbuffer}, SCSCP_status* @var{status} )
@end deftypefn


It sends a "procedure completed" message to the SCSCP client  with the @var{options}. The string @var{openmathbuffer} is the argument of the "procedure completed".

The string @var{openmathbuffer} must be a valid OpenMath command or @code{NULL}. 

@funcfailssetstatus{SCSCP_ss_sendcompletedstr} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_ss_sendcompletedhook
@deftypefn {Library Function} int SCSCP_ss_sendcompletedhook ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_returnoptions* @var{options},  int (*@var{callbackwriteargs})(SCSCP_io* stream, void *param, SCSCP_status* status), void* @var{param}, SCSCP_status* @var{status})
@end deftypefn

It sends a "procedure completed" message to the client with the @var{options}. The arguments of the "procedure completed" message must be written by the callback function @var{callbackwriteargs}. The function @var{callbackwriteargs} must use the I/O functions @code{SCSCP_io_writexxx}, such as @code{SCSCP_io_writeOMSTR}, to write data which are sent to the SCSCP client.

The argument @var{param} is a pointer which is provided to the @var{callbackwriteargs} to exchange information. This pointer and its content isn't modified by @code{SCSCP_ss_sendcompletedhook}.  

@funcfailssetstatus{SCSCP_ss_sendcompletedhook} @value{statusignoremessage} 



@c %-----------------------
@subsection SCSCP_ss_infomessagesend
@deftypefn {Library Function} int SCSCP_ss_infomessagesend ( SCSCP_incomingclient* @var{incomingclient}, const char* @var{messagebuffer}, SCSCP_status* @var{status} )
@end deftypefn


It sends an information message to the SCSCP client for a debugging purpose.
The string @var{messagebuffer} must be a valid string. 

@funcfailssetstatus{SCSCP_ss_infomessagesend} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_ss_set_encodingtype

@deftypefn {Library Function} int SCSCP_ss_set_encodingtype ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_encodingtype @var{encodingtype}, SCSCP_status* @var{status} )

@end deftypefn
This function sets the current encoding of the OpenMath objects used by the SCSCP server to send an answer. The provided Openmath buffers, such as for the call @code{SCSCP_ss_sendcompletedstr}, must use the same encoding.

The default encoding for the SCSCP server is the @code{SCSCP_encodingtype_XML}. 

@funcfailssetstatus{SCSCP_ss_set_encodingtype} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_ss_get_encodingtype

@deftypefn {Library Function} int SCSCP_ss_set_encodingtype ( SCSCP_incomingclient* @var{incomingclient}, SCSCP_encodingtype* @var{encodingtype}, SCSCP_status* @var{status} )

@end deftypefn
This function returns, in the argument @var{encodingtype}, the current encoding for the OpenMath objects when the SCSCP server sends an answer.

@funcfailssetstatus{SCSCP_ss_get_encodingtype} @value{statusignoremessage} 



@c %----------------------------------------------------------------------------
@node Client functions, I/O functions, Server functions, @value{LIBRARYCNAME} Interface
@section Client functions

The following functions manage all operations on the @code{SCSCP_socketclient} object.

@subsection SCSCP_sc_init

@deftypefn {Library Function} int SCSCP_sc_init
            ( SCSCP_socketclient* @var{client},  SCSCP_status* @var{status}, ... )
@end deftypefn
 
It initializes the internal structure of the object @var{client}. The variadic arguments should be of the type @code{const char*} and the last argument must be @code{NULL}. The variadic parameters define the allowed version of SCSCP protocol that could be negotiated with the SCSCP server.

During the negotiation with the server, the client will choose the first version in the variadic parameters that the server supports too. So the variadic parameters should start by from the highest level of the SCSCP version to the lowest version. 

The constants @code{SCSCP_PROTOCOL_VERSION_x_x} could be used for the variadic  parameters.

@funcfailssetstatus{SCSCP_sc_init} @value{statusignoremessage} 


@cartouche
@example
res = SCSCP_sc_init(&client, &status, SCSCP_PROTOCOL_VERSION_1_3,
                    "1.0beta", NULL);
@end example
@end cartouche

@c %-----------------------
@subsection SCSCP_sc_clear

@deftypefn {Library Function} int SCSCP_sc_clear ( SCSCP_socketclient* @var{client},  SCSCP_status* @var{status} )
@end deftypefn
 
It clears  the internal structure of the object @var{client} and frees allocated memory for this object by the function @code{SCSCP_sc_init}.
If a connection was already opened, the function @code{SCSCP_sc_close} is called before clearing the object.

@funcfailssetstatus{SCSCP_sc_clear} @value{statusignoremessage} 



@c %-----------------------
@subsection SCSCP_sc_connect

@deftypefn {Library Function} int SCSCP_sc_connect
            ( SCSCP_socketclient* @var{client},  const char *@var{machine}, int @var{port}, SCSCP_status* @var{status} )

@end deftypefn

It tries to connect to the SCSCP server which is running on the computer @var{machine} and is listening on the port @var{port}. 

@var{client} must be initialized with the function @code{SCSCP_sc_init} before calling this function. If the connection achieves, @var{client} is updated on exit.


@var{machine} could be any string but it must resolved as an IP address. Its value could be  "localhost" if the SCSCP server runs on the same computer.

In most of the case, the default value @var{SCSCP_PROTOCOL_DEFAULTPORT} should be used for the port number.

@funcfailssetstatus{SCSCP_sc_connect} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_sc_close

@deftypefn {Library Function} int SCSCP_sc_close ( SCSCP_socketclient* @var{client}, SCSCP_status* @var{status} )

@end deftypefn
It closes a connection previously opened by a SCSCP client with the function @code{SCSCP_sc_connect}.

@funcfailssetstatus{SCSCP_sc_close} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_sc_set_encodingtype

@deftypefn {Library Function} int SCSCP_sc_set_encodingtype ( SCSCP_socketclient* @var{client}, SCSCP_encodingtype @var{encodingtype}, SCSCP_status* @var{status} )

@end deftypefn
This function sets the current encoding of the OpenMath objects used by the SCSCP client to send a "procedure call" message. The provided Openmath buffers, such as for the call @code{SCSCP_sc_callsendstr}, must use the same encoding.

The default encoding for the SCSCP client is the @code{SCSCP_encodingtype_XML}. 

@funcfailssetstatus{SCSCP_sc_set_encodingtype} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_sc_get_encodingtype

@deftypefn {Library Function} int SCSCP_sc_set_encodingtype ( SCSCP_socketclient* @var{client}, SCSCP_encodingtype* @var{encodingtype}, SCSCP_status* @var{status} )

@end deftypefn
This function returns, in the argument @var{encodingtype}, the current encoding for the OpenMath objects when the SCSCP client sends a "procedure call" message.

@funcfailssetstatus{SCSCP_sc_get_encodingtype} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_sc_callsendstr

@deftypefn {Library Function} int SCSCP_sc_callsendstr ( SCSCP_socketclient* @var{client}, SCSCP_calloptions* @var{options},  const char * @var{openmathbuffer}, SCSCP_status* @var{status} )
@end deftypefn


The @var{client} sends a "procedure call" message to the SCSCP server  with the @var{options}. The string @var{openmathbuffer} is the argument of the procedure call.
A connection must be previously opened with @code{SCSCP_sc_connect} before preforming this procedure call. 

The string @var{openmathbuffer} must be an OpenMath Application object. 

The value @code{SCSCP_CALLOPTIONS_DEFAULT} could be used for the parameter @var{options}  in order to use the default procedure call options. The procedure call options could be set using the functions @code{SCSCP_co_set_xxx}.
                 

@funcfailssetstatus{SCSCP_sc_callsendstr} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_sc_callrecvstr
@deftypefn {Library Function} int SCSCP_sc_callrecvstr ( SCSCP_socketclient* @var{client}, SCSCP_returnoptions* @var{options}, SCSCP_msgtype* @var{msgtype}, char** @var{openmathbuffer}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} reads the attribute, the type and the content of the message returned by the server in response of a procedure call. 

On exit, the argument @var{msgtype} contains the message type returned by the server.  
On exit, the argument @var{openmathbuffer} contains the content of the message returned by the server.  This string must be freed by the system call @code{free}.

The value @code{SCSCP_RETURNOPTIONS_IGNORE} could be used for the parameter @var{options} in order to ignore the returned value. The return options could be get using the functions @code{SCSCP_ro_get_xxx}. If @var{options} isn't @code{SCSCP_RETURNOPTIONS_IGNORE}, it must be initialized before with the function @code{SCSCP_ro_init}.


@funcfailssetstatus{SCSCP_sc_callrecvstr} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_sc_callsendhook
@deftypefn {Library Function} int SCSCP_sc_callsendhook ( SCSCP_socketclient* @var{client}, SCSCP_calloptions* @var{options},  int (*@var{callbackwriteappli})(SCSCP_io* stream, void *param, SCSCP_status* status), void* @var{param}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} sends a "procedure call" message  to the server with the @var{options}. The arguments of the procedure call must be written by the callback function @var{callbackwriteappli}. The function @var{callbackwriteappli} must use the functions @code{SCSCP_io_writexxx}, such as @code{SCSCP_io_writeOMSTR}, to write data which are sent to the SCSCP server.
The function @var{callbackwriteappli} must write an OpenMath Application object.
A connection must be previously opened with @code{SCSCP_sc_connect} before preforming this procedure call. 

The argument @var{param} is a pointer which is provided to  the @var{callbackwriteargs} to exchange information. This pointer and its content isn't modified by @code{SCSCP_sc_callsendhook}.  

The value @code{SCSCP_CALLOPTIONS_DEFAULT} could be used for the parameter @var{options} in order to use the default procedure call options. The procedure call options could be set using the functions @code{SCSCP_co_set_xxx}.

@funcfailssetstatus{SCSCP_sc_callsendhook} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_sc_callrecvheader
@deftypefn {Library Function} int SCSCP_sc_callrecvheader ( SCSCP_socketclient* @var{client}, SCSCP_returnoptions* @var{options}, SCSCP_msgtype* @var{msgtype}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} reads the attribute and type of the message returned by the server in response of a procedure call. 

The value @code{SCSCP_RETURNOPTIONS_IGNORE} could be used for the parameter @var{options} in order to ignore the returned value. The return options could be get using the functions @code{SCSCP_ro_get_xxx}. If @var{options} isn't @code{SCSCP_RETURNOPTIONS_IGNORE}, it must be initialized before with the function @code{SCSCP_ro_init}.

On exit, the argument @var{msgtype} contains the message type returned by the server.  

@funcfailssetstatus{SCSCP_sc_callrecvheader} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_sc_callrecvterminated
@deftypefn {Library Function} int SCSCP_sc_callrecvterminated ( SCSCP_socketclient* @var{client},  char ** @var{cdname}, char ** @var{symbolname}, char** @var{messagebuffer}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} reads the content of the OpenMath error if the server replies with a "procedure terminated" message. This function must be called only if @code{SCSCP_sc_callrecvheader} returns  @var{msgtype}=@code{SCSCP_msgtype_ProcedureTerminated}.

On exit, the argument @var{symbolname} contains the name of the OpenMath symbol from the OpenMath content dictionnary @var{cdname}. These strings must be freed by the system call @code{free}.  
On exit, the argument @var{messagebuffer} contains the full content of the error (including the head symbol of the OpenMath error) returned by the server.  This string must be freed by the system call @code{free}.

@funcfailssetstatus{SCSCP_sc_callrecvterminated} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_sc_callrecvcompleted
@deftypefn {Library Function} int SCSCP_sc_callrecvcompleted ( SCSCP_socketclient* @var{client}, char** @var{openmathbuffer}, SCSCP_status* @var{status})
@end deftypefn
The @var{client} reads the content of the messages if the server replies with a "procedure completed" message. This function must be called only if @code{SCSCP_sc_callrecvheader} returns  @var{msgtype}=@code{SCSCP_msgtype_ProcedureCompleted}.

On exit, the argument @var{openmathbuffer} contains the content of the message returned by the server.  This string must be freed by the system call @code{free}.

@funcfailssetstatus{SCSCP_sc_callrecvcompleted} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_sc_callsendinterrupt
@deftypefn {Library Function} int SCSCP_sc_callsendinterrupt ( SCSCP_socketclient* @var{client}, const char* @var{call_id}, SCSCP_status* @var{status} )
@end deftypefn


It sends an interrupt signal to the SCSCP server with the call ID @var{call_id}. The server need not to complete the computation but the server will always reply to the procedure call.
The argument @var{call_id} can't be NULL.

@funcfailssetstatus{SCSCP_sc_callsendinterrupt} @value{statusignoremessage} 


@c %--------------------------
@subsection SCSCP_sc_executehookxmlnode
@deftypefn {Library Function} int SCSCP_sc_executehookxmlnode ( SCSCP_socketclient* @var{client}, SCSCP_option_return @var{returntype},  const char * @var{cdname}, const char* @var{symbolname}, int (*@var{callbackwriteargs})(SCSCP_io* stream, void *param, SCSCP_status* status), void* @var{param}, SCSCP_xmlnodeptr* @var{node}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} sends a "procedure call" message  to the server with an OpenMath symbol @var{symbolname} from the content dictionary @var{cdname} as first argument. The other arguments of the procedure call must be written by the callback function @var{callbackwriteargs}. The function @var{callbackwriteargs} must use the functions @code{SCSCP_io_writexxx}, such as @code{SCSCP_io_writeOMSTR}, to write data which are sent to the SCSCP server.
A connection must be previously opened with @code{SCSCP_sc_connect} before preforming this procedure call. 

The argument @var{param} is a pointer which is provided to the @var{callbackwriteargs} to exchange information. This pointer and its content isn't modified by @code{SCSCP_sc_executehookxmlnode}.  

The server returns a result (object, cookie, nothing) depending on the value  @var{returntype}. On exit, the argument @var{node} contains a pointer to the OpenMath object by the server. 

@funcfailssetstatus{SCSCP_sc_executehookxmlnode} @value{statusignoremessage} 

@c %--------------------------
@subsection SCSCP_sc_executehookstr
@deftypefn {Library Function} int SCSCP_sc_executehookstr ( SCSCP_socketclient* @var{client}, SCSCP_option_return @var{returntype},  const char * @var{cdname}, const char* @var{symbolname}, int (*@var{callbackwriteargs})(SCSCP_io* stream, void *param, SCSCP_status* status), void* @var{param}, char ** @var{openmathbuffer}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} sends a "procedure call" message  to the server with an OpenMath symbol @var{symbolname} from the content dictionary @var{cdname} as first argument. The other arguments of the procedure call must be written by the callback function @var{callbackwriteargs}. The function @var{callbackwriteargs} must use the functions @code{SCSCP_io_writexxx}, such as @code{SCSCP_io_writeOMSTR}, to write data which are sent to the SCSCP server.
A connection must be previously opened with @code{SCSCP_sc_connect} before preforming this procedure call. 

The argument @var{param} is a pointer which is provided to the @var{callbackwriteargs} to exchange information. This pointer and its content isn't modified by @code{SCSCP_sc_callsendhookstr}.  

The server returns a result (object, cookie, nothing) depending on the value  @var{returntype}. On exit, the argument @var{openmathbuffer} contains a string representing the OpenMath object by the server. 

@funcfailssetstatus{SCSCP_sc_callsendhookstr} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_sc_infomessagesend
@deftypefn {Library Function} int SCSCP_sc_infomessagesend ( SCSCP_socketclient* @var{client}, const char* @var{messagebuffer}, SCSCP_status* @var{status} )
@end deftypefn


It sends an information message to the SCSCP server for a debugging purpose.
The string @var{messagebuffer} must be a valid string. 

@funcfailssetstatus{SCSCP_sc_infomessagesend} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_sc_getxmlnode
@deftypefn {Library Function} SCSCP_xmlnodeptr SCSCP_sc_getxmlnode ( SCSCP_socketclient* @var{client}, SCSCP_status* @var{status})
@end deftypefn
The @var{client} returns a pointer to the current XML tree. This function could be used to start parsing the message sent by the server. This pointer is valid until the next call to the functions @code{SCSCP_sc_callrecv...}.

@funcfailsptrsetstatus{SCSCP_sc_getxmlnode} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_sc_getxmlnoderawstring
@deftypefn {Library Function}  char * SCSCP_sc_getxmlnoderawstring ( SCSCP_socketclient* @var{client}, SCSCP_xmlnodeptr @var{curnode}, SCSCP_status* @var{status})
@end deftypefn
This function returns the content of the current node @var{curnode} and its children as a string.
This string must be freed by the system call @code{free}.

@funcfailsptrsetstatus{SCSCP_sc_getxmlnoderawstring} @value{statusignoremessage} 

@c %-----------------------
@node  I/O functions,Status functions, Client functions, @value{LIBRARYCNAME} Interface
@section I/O functions

@c %-----------------------
@subsection SCSCP_io_write
@deftypefn {Library Function} int SCSCP_io_write ( SCSCP_io* @var{stream}, const char *@var{buffer}, SCSCP_status* @var{status} )
@end deftypefn

It writes the data @var{buffer} directly to the @var{stream}. The argument @var{buffer} can't be NULL.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 
 
@funcfailssetstatus{SCSCP_io_write} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeOMSTR
@deftypefn {Library Function} int SCSCP_io_writeOMSTR ( SCSCP_io* @var{stream}, const char *@var{buffer}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

 It writes the data @var{buffer} as an OpenMath string @code{<OMSTR>...</OMSTR>} to the @var{stream}.
 If the argument @var{buffer} is NULL, the OpenMath string is encoding with only one space.
 @paramid
 
This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMSTR} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeOMFdouble
@deftypefn {Library Function} int SCSCP_io_writeOMFdouble ( SCSCP_io* @var{stream}, double @var{x}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the floating-point number @var{x} as an OpenMath float @code{<OMF dec="..." />} to the @var{stream}.
 @paramid
 
This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMFdouble} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeOMFstr
@deftypefn {Library Function} int SCSCP_io_writeOMFstr ( SCSCP_io* @var{stream}, const char* @var{buffer}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the floating-point number @var{buffer} as an OpenMath float @code{<OMF dec="..." />} to the @var{stream}.
The argument @var{buffer} can't be NULL.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMFstr} @value{statusignoremessage} 



@c %-----------------------
@subsection SCSCP_io_writeOMIint
@deftypefn {Library Function} int SCSCP_io_writeOMIint ( SCSCP_io* @var{stream}, int @var{x}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the integer @var{x} as an OpenMath integer @code{<OMI>...</OMI>} to the @var{stream}.
 @paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMIint} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeOMIlonglong
@deftypefn {Library Function} int SCSCP_io_writeOMIlonglong ( SCSCP_io* @var{stream}, long long @var{x}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the integer @var{x} as an OpenMath integer @code{<OMI>...</OMI>} to the @var{stream}.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMIlonglong} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_io_writeOMIstr
@deftypefn {Library Function} int SCSCP_io_writeOMIstr ( SCSCP_io* @var{stream}, const char* @var{buffer}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the integer @var{buffer} as an OpenMath integer @code{<OMI>...</OMI>} to the @var{stream}.
The argument @var{buffer} can't be NULL.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMIstr} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeOMS
@deftypefn {Library Function} int SCSCP_io_writeOMS ( SCSCP_io* @var{stream}, const char* @var{cdname}, const char* @var{symbolname}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the symbol @var{symbolname} of the Content Dictionary @var{cdname} as an OpenMath symbol @code{<OMS cd="..." name="..." />} to the @var{stream}.
The argument @var{cdname} and @var{symbolname} can't be NULL.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMS} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeOMV
@deftypefn {Library Function} int SCSCP_io_writeOMV ( SCSCP_io* @var{stream}, const char* @var{buffer}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the variable @var{buffer} as an OpenMath variable @code{<OMV name="..." />} to the @var{stream}.
The argument @var{buffer} can't be NULL.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMV} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeOMR
@deftypefn {Library Function} int SCSCP_io_writeOMR ( SCSCP_io* @var{stream}, const char* @var{buffer}, SCSCP_status* @var{status} )
@end deftypefn

It writes the reference @var{buffer} as an OpenMath reference @code{<OMR href="..."/>} to the @var{stream}.
The argument @var{buffer} can't be NULL.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMR} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeOMB
@deftypefn {Library Function} int SCSCP_io_writeOMB ( SCSCP_io* @var{stream}, const void* @var{buffer}, size_t lenbuffer SCSCP_status* @var{status} )
@end deftypefn

It writes the array @var{buffer} of @var{lenbuffer} bytes as an OpenMath byte array @code{<OMB/>...</OMB>} to the @var{stream}.
The argument @var{buffer} can't be NULL.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeOMB} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writebeginOMA
@deftypefn {Library Function} int SCSCP_io_writebeginOMA ( SCSCP_io* @var{stream}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the beginning of the structured Open Math object @code{<OMA>} to the stream @var{stream}.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writebeginOMA} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeendOMA
@deftypefn {Library Function} int SCSCP_io_writeendOMA ( SCSCP_io* @var{stream}, SCSCP_status* @var{status} )
@end deftypefn

It writes the end of the structured Open Math object @code{</OMA>} to the @var{stream}.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeendOMA} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writebeginOMATP
@deftypefn {Library Function} int SCSCP_io_writebeginOMATP ( SCSCP_io* @var{stream}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the beginning of the structured Open Math attribute pair @code{<OMATP>} to the stream @var{stream}.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writebeginOMATP} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeendOMATP
@deftypefn {Library Function} int SCSCP_io_writeendOMATP ( SCSCP_io* @var{stream}, SCSCP_status* @var{status} )
@end deftypefn

It writes the end of the structured Open Math attribute pair @code{</OMATP>} to the @var{stream}.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeendOMATP} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writebeginOMATTR
@deftypefn {Library Function} int SCSCP_io_writebeginOMATTR ( SCSCP_io* @var{stream}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the beginning of the structured Open Math attribution @code{<OMATTR>} to the stream @var{stream}.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writebeginOMATTR} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeendOMATTR
@deftypefn {Library Function} int SCSCP_io_writeendOMATTR ( SCSCP_io* @var{stream}, SCSCP_status* @var{status} )
@end deftypefn

It writes the end of the structured Open Math attribution @code{</OMATTR>} to the @var{stream}.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeendOMATTR} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writebeginOMBIND
@deftypefn {Library Function} int SCSCP_io_writebeginOMBIND ( SCSCP_io* @var{stream}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the beginning of the structured Open Math binding object @code{<OMBIND>} to the stream @var{stream}.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writebeginOMBIND} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeendOMBIND
@deftypefn {Library Function} int SCSCP_io_writeendOMBIND ( SCSCP_io* @var{stream}, SCSCP_status* @var{status} )
@end deftypefn

It writes the end of the structured Open Math binding object @code{</OMBIND>} to the @var{stream}.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeendOMBIND} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_io_writebeginOME
@deftypefn {Library Function} int SCSCP_io_writebeginOME ( SCSCP_io* @var{stream}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the beginning of the structured Open Math error @code{<OME>} to the stream @var{stream}.
@paramid

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writebeginOME} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeendOME
@deftypefn {Library Function} int SCSCP_io_writeendOME ( SCSCP_io* @var{stream}, SCSCP_status* @var{status} )
@end deftypefn

It writes the end of the structured Open Math error @code{</OME>} to the @var{stream}.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeendOME} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writebeginOMFOREIGN
@deftypefn {Library Function} int SCSCP_io_writebeginOMFOREIGN ( SCSCP_io* @var{stream}, const char *@var{id}, SCSCP_status* @var{status} )
@end deftypefn

It writes the beginning of the structured Open Math foreign object @code{<OMFOREIGN>} to the stream @var{stream}.
@paramid 
 Currently, the binary encoding isn't supported, the function always fails.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writebeginOMFOREIGN} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeendOMFOREIGN
@deftypefn {Library Function} int SCSCP_io_writeendOMFOREIGN ( SCSCP_io* @var{stream}, SCSCP_status* @var{status} )
@end deftypefn

It writes the end of the structured Open Math foreign object @code{</OMFOREIGN>} to the @var{stream}
 Currently, the binary encoding isn't supported, the function always fails.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeendOMFOREIGN} @value{statusignoremessage} 


@c %-----------------------
@subsection SCSCP_io_writebeginOMOBJ
@deftypefn {Library Function} int SCSCP_io_writebeginOMOBJ ( SCSCP_io* @var{stream}, SCSCP_status* @var{status} )
@end deftypefn

It writes the beginning of the structured Open Math object @code{<OMOBJ>} to the stream @var{stream}.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writebeginOMOBJ} @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_io_writeendOMOBJ
@deftypefn {Library Function} int SCSCP_io_writeendOMOBJ ( SCSCP_io* @var{stream}, SCSCP_status* @var{status} )
@end deftypefn

It writes the end of the structured Open Math object @code{</OMOBJ>} to the @var{stream}.

This function must only be called by the callback function @var{callbackwritearg} provided to the hook functions @code{SCSCP_ss_sendcompletedhook}, @code{SCSCP_sc_callsendhook}, .... 

@funcfailssetstatus{SCSCP_io_writeendOMOBJ} @value{statusignoremessage} 




@c %-----------------------
@node Status functions, Procedure call options functions, I/O functions, @value{LIBRARYCNAME} Interface
@section Status functions


@c %-----------------------
@subsection SCSCP_status_clear

@deftypefn {Library Function} void SCSCP_status_clear (SCSCP_status* @var{status} )
@end deftypefn
 
It clears  the internal structure of the object @var{status} and frees allocated memory for this object by any error of the library.


@c %-----------------------
@subsection SCSCP_status_is
@deftypefn {Library Function} int SCSCP_status_is ( SCSCP_status* @var{status} )
@end deftypefn

This function returns the integer value of the status object. The returned value are defined in @xref{SCSCP_status}. @var{status} mustn't be @code{SCSCP_STATUS_IGNORE}.
This function could be defined as a macro in the header file @file{scscp.h}.

@cartouche
@example
 int res = SCSCP_co_get_maxmemory(&options, &memsize, status);
 if (res) 
 @{
   printf("maximum memory = %lld\n", (long long)memsize);
 @}
 else if (SCSCP_status_is(status)==SCSCP_STATUS_USAGEUNKNOWNMAXMEMORY)
 @{
   printf("maximum memory not available\n");
 @}
@end example
@end cartouche

@c %-----------------------
@subsection SCSCP_status_strerror
@deftypefn {Library Function} {const char*} SCSCP_status_strerror (const SCSCP_status* @var{status} )
@end deftypefn

This function accepts an argument @var{status} and returns a pointer to the corresponding message string.
@cartouche
@example
 int res = SCSCP_co_get_maxmemory(&options, &memsize, status);
 if (res) 
 @{
   printf("maximum memory = %lld\n", (long long)memsize);
 @}
 else 
 @{
   printf("error message ='%s'\n", SCSCP_status_strerror(status));
 @}
@end example
@end cartouche


@c %-----------------------
@node Procedure call options functions, Procedure return options functions , Status functions, @value{LIBRARYCNAME} Interface
@section Procedure call options functions

@subsection SCSCP_co_init
@deftypefn {Library Function} int SCSCP_co_init ( SCSCP_calloptions* @var{options}, SCSCP_status* @var{status} )
@end deftypefn

It initializes the internal structure of the object @var{options}. 
It generates and sets the call identifier of the options of the procedure call. This call identifier is defined as the symbol @code{call_id} of the OpenMath Content Dictionary @code{scscp1}. The call identifier is prefixed by @code{libSCSCP:}. It sets the return type to the value @code{SCSCP_option_return_object}.
 
@funcfailssetstatus{SCSCP_co_init} @value{statusignoremessage} 

@subsection SCSCP_co_clear
@deftypefn {Library Function} int SCSCP_co_clear ( SCSCP_calloptions* @var{options}, SCSCP_status* @var{status} )
@end deftypefn

It clears the internal structure of the object @var{options} and frees allocated memory for this object by the function @code{SCSCP_co_init}. 
 
@funcfailssetstatus{SCSCP_co_clear} @value{statusignoremessage} 


@subsection SCSCP_co_set_callid
@deftypefn {Library Function} int SCSCP_co_set_callid ( SCSCP_calloptions* @var{options}, const char *@var{buffer}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the call identifier of the options of the procedure call. It overwrites the default call identifier, generated by @code{SCSCP_co_init}. This call identifier is defined as the symbol @code{call_id} of the OpenMath Content Dictionary @code{scscp1}. 

The argument @var{buffer} can't be NULL and won't be duplicated by these functions. So @var{buffer} mustn't be destroyed until the function @code{SCSCP_co_clear} is called on the object @var{options}. The argument @var{buffer} shouldn't be use any string beginning with @code{libSCSCP:} because @code{SCSCP_co_init} generates unique call identifier with this prefix. The caller of this function is resposible of the unicity of the content of @var{buffer} during th connection.
 
@funcfailssetstatus{SCSCP_co_set_callid} @value{statusignoremessage} 


@subsection SCSCP_co_get_callid
@deftypefn {Library Function} int SCSCP_co_get_callid ( SCSCP_calloptions* @var{options}, const char **@var{buffer}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{buffer}, the call id of the options of the procedure call. This call id is defined as the symbol @code{call_id} of the OpenMath Content Dictionary @code{scscp1}. The argument @var{buffer} can't be NULL. The returned string mustn't be modified.
 
@funcfailssetstatus{SCSCP_co_get_callid} @value{statusignoremessage} 



@subsection SCSCP_co_set_runtimelimit
@deftypefn {Library Function} int SCSCP_co_set_runtimelimit ( SCSCP_calloptions* @var{options}, size_t @var{time}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the amount of time in milliseconds, with the value @var{time},  that the SCSCP server should spend on this call. This runtime limit is defined by the symbol @code{option_runtime} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcfailssetstatus{SCSCP_co_set_runtimelimit} @value{statusignoremessage} 


@subsection SCSCP_co_get_runtimelimit
@deftypefn {Library Function} int SCSCP_co_get_runtimelimit ( SCSCP_calloptions* @var{options}, size_t* @var{time}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{time}, the amount of time in milliseconds  that the server should spend on this call. This amount of time is defined as the symbol @code{option_runtime} of the OpenMath Content Dictionary @code{scscp1}. If the amount of time isn't available (not supplied by the server), the function fails and @var{status} is set to @code{SCSCP_STATUS_USAGEUNKNOWNRUNTIMELIMIT}.

The argument @var{time} can't be NULL. 

@funcfailssetstatus{SCSCP_co_get_runtimelimit}  @value{statusignoremessage} 



@subsection SCSCP_co_set_minmemory
@deftypefn {Library Function} int SCSCP_co_set_minmemory ( SCSCP_calloptions* @var{options}, size_t @var{memsize}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the minimum amount of memory in bytes, with the value @var{memsize}, that the server should use on this call. This memory limit is defined by the symbol @code{option_min_memory} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcfailssetstatus{SCSCP_co_set_minmemory} @value{statusignoremessage} 

@subsection SCSCP_co_get_minmemory
@deftypefn {Library Function} int SCSCP_co_get_minmemory ( SCSCP_calloptions* @var{options}, size_t* @var{memsize}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{memsize}, the minimum amount of memory in bytes that the server should use on this call. This amount of memory is defined as the symbol @code{option_min_memory} of the OpenMath Content Dictionary @code{scscp1}. If the amount of memory isn't available (not supplied by the server), the function fails and @var{status} is set to @code{SCSCP_STATUS_USAGEUNKNOWNMINMEMORY}.

The argument @var{memsize} can't be NULL. 

@funcfailssetstatus{SCSCP_co_get_minmemory}  @value{statusignoremessage} 

@subsection SCSCP_co_set_maxmemory
@deftypefn {Library Function} int SCSCP_co_set_maxmemory ( SCSCP_calloptions* @var{options}, size_t @var{memsize}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the maximum amount of memory in bytes, with the value @var{memsize},  that the SCSCP server should use on this call. This memory limit is defined by the symbol @code{option_max_memory} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcfailssetstatus{SCSCP_co_set_maxmemory} @value{statusignoremessage} 


@subsection SCSCP_co_get_maxmemory
@deftypefn {Library Function} int SCSCP_co_get_maxmemory ( SCSCP_calloptions* @var{options}, size_t* @var{memsize}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{memsize}, the maximum amount of memory in bytes that the server should use on this call. This amount of memory is defined as the symbol @code{option_max_memory} of the OpenMath Content Dictionary @code{scscp1}. If the amount of memory isn't available (not supplied by the server), the function fails and @var{status} is set to @code{SCSCP_STATUS_USAGEUNKNOWNMAXMEMORY}.

The argument @var{memsize} can't be NULL. 

@funcfailssetstatus{SCSCP_co_get_maxmemory}  @value{statusignoremessage} 

@subsection SCSCP_co_set_debuglevel
@deftypefn {Library Function} int SCSCP_co_set_debuglevel ( SCSCP_calloptions* @var{options}, int @var{debuglevel}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the debug level, with the value @var{debuglevel}, that the client is interested. This debug level is defined by the symbol @code{option_debuglevel} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcfailssetstatus{SCSCP_co_set_debuglevel} @value{statusignoremessage} 


@subsection SCSCP_co_get_debuglevel
@deftypefn {Library Function} int SCSCP_co_get_debuglevel ( SCSCP_calloptions* @var{options}, int* @var{debuglevel}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{debuglevel}, the debug level that the client is interested. This debug level is defined as the symbol @code{option_max_memory} of the OpenMath Content Dictionary @code{scscp1}. If the debug level isn't available (not supplied by the server), the function fails and @var{status} is set to @code{SCSCP_STATUS_USAGEUNKNOWNDEBUGLEVEL}.

The argument @var{debuglevel} can't be NULL. 

@funcfailssetstatus{SCSCP_co_get_debuglevel}  @value{statusignoremessage} 


@subsection SCSCP_co_set_returntype
@deftypefn {Library Function} int SCSCP_co_set_returntype ( SCSCP_calloptions* @var{options}, SCSCP_option_return @var{returntype}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the return type, with the value @var{returntype}, of the procedure call that the server should send. The available value for @var{returntype} are

@itemize
@item @code{SCSCP_option_return_object}. The return value is an OpenMath object. It's defined by the symbol @code{option_return_object} of the OpenMath Content Dictionary @code{scscp1}.
@item @code{SCSCP_option_return_cookie}. The return value is a cookie (a reference to an OpenMath object). It's defined by the symbol @code{option_return_cookie} of the OpenMath Content Dictionary @code{scscp1}.
@item @code{SCSCP_option_return_nothing}. The procedure call returns no value. It's defined by the symbol @code{option_return_nothing} of the OpenMath Content Dictionary @code{scscp1}.
@end itemize

@funcfailssetstatus{SCSCP_co_set_returntype} @value{statusignoremessage} 

@subsection SCSCP_co_get_returntype
@deftypefn {Library Function} int SCSCP_co_get_returntype ( SCSCP_calloptions* @var{options}, SCSCP_option_return* @var{returntype}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{returntype}, the return type of the "procedure call" message that the server should send. The possible value of @var{returntype} are described in the function  @code{SCSCP_co_set_returntype}.
 If the return type isn't available (not supplied by the server), the function fails and @var{status} is set to @code{SCSCP_STATUS_USAGEUNKNOWNRETURNTYPE}.

The argument @var{returntype} can't be NULL. 

@funcfailssetstatus{SCSCP_co_get_returntype}  @value{statusignoremessage} 

@c %-----------------------
@subsection SCSCP_co_get_encodingtype

@deftypefn {Library Function} int SCSCP_co_get_encodingtype ( SCSCP_calloptions* @var{options}, SCSCP_encodingtype* @var{encodingtype}, SCSCP_status* @var{status} )

@end deftypefn
This function returns, in the argument @var{encodingtype}, the current encoding for the OpenMath objects associated with this "procedure call" message.

@funcfailssetstatus{SCSCP_co_get_encodingtype} @value{statusignoremessage} 


@c %-----------------------
@node Procedure return options functions , XML parsing functions,  Procedure call options functions, @value{LIBRARYCNAME} Interface
@section Procedure return options functions

@subsection SCSCP_ro_init
@deftypefn {Library Function} int SCSCP_ro_init ( SCSCP_returnoptions* @var{options}, SCSCP_status* @var{status} )
@end deftypefn

It initializes the internal structure of the object @var{options}. 
 
@funcfailssetstatus{SCSCP_ro_init} @value{statusignoremessage} 

@subsection SCSCP_ro_clear
@deftypefn {Library Function} int SCSCP_ro_clear ( SCSCP_returnoptions* @var{options}, SCSCP_status* @var{status} )
@end deftypefn

It clears the internal structure of the object @var{options} and frees allocated memory for this object by the function @code{SCSCP_ro_init}. 
 
@funcfailssetstatus{SCSCP_ro_clear} @value{statusignoremessage} 


@subsection SCSCP_ro_set_callid
@deftypefn {Library Function} int SCSCP_ro_set_callid ( SCSCP_returnoptions* @var{options}, const char *@var{buffer}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the call id, with the value @var{buffer}, of the options of the procedure return. This call id is defined as the symbol @code{call_id} of the OpenMath Content Dictionary @code{scscp1}. The argument @var{buffer} can't be NULL and won't be duplicated by this function. So @var{buffer} can't be destroyed until the function @code{SCSCP_ro_clear} is called on the object @var{options}.
 
@funcfailssetstatus{SCSCP_ro_set_callid} @value{statusignoremessage} 


@subsection SCSCP_ro_get_callid
@deftypefn {Library Function} int SCSCP_ro_get_callid ( SCSCP_returnoptions* @var{options}, const char **@var{buffer}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{buffer}, the call id of the options of the procedure return. This call id is defined as the symbol @code{call_id} of the OpenMath Content Dictionary @code{scscp1}. The argument @var{buffer} mustn't be NULL. The returned string mustn't be modified.
 
@funcfailssetstatus{SCSCP_ro_get_callid} @value{statusignoremessage} 


@subsection SCSCP_ro_set_runtime
@deftypefn {Library Function} int SCSCP_ro_set_runtime ( SCSCP_returnoptions* @var{options}, size_t @var{time}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the amount of time in milliseconds, with the value @var{time}, that the server spent on this call. This amount of time is defined as the symbol @code{info_runtime} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcfailssetstatus{SCSCP_ro_set_runtime} @value{statusignoremessage} 

@subsection SCSCP_ro_get_runtime
@deftypefn {Library Function} int SCSCP_ro_get_runtime ( SCSCP_returnoptions* @var{options}, size_t* @var{time}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{time}, the amount of time in milliseconds  that the server spent on this call. This amount of time is defined as the symbol @code{info_runtime} of the OpenMath Content Dictionary @code{scscp1}. If the amount of time isn't available (not supplied by the server), the function fails and @var{status} is set to @code{SCSCP_STATUS_USAGEUNKNOWNRUNTIME}.

The argument @var{time} can't be NULL. 

@funcfailssetstatus{SCSCP_ro_get_runtime}  @value{statusignoremessage} 


@subsection SCSCP_ro_set_memory
@deftypefn {Library Function} int SCSCP_ro_set_memory ( SCSCP_returnoptions* @var{options}, size_t @var{memsize}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the amount of memory in bytes, with the value @var{memsize},  that the server used on this call. This amount of memory is defined as the symbol @code{info_memory} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcfailssetstatus{SCSCP_ro_set_memory} @value{statusignoremessage} 


@subsection SCSCP_ro_get_memory
@deftypefn {Library Function} int SCSCP_ro_get_memory ( SCSCP_returnoptions* @var{options}, size_t* @var{memsize}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{memsize}, the amount of memory in bytes that the server used for this call. This amount of memory is defined as the symbol @code{info_memory} of the OpenMath Content Dictionary @code{scscp1}. If the amount of memory isn't available (not supplied by the server), the function fails and @var{status} is set to @code{SCSCP_STATUS_USAGEUNKNOWNMEM}.

The argument @var{memsize} can't be NULL. 

@funcfailssetstatus{SCSCP_ro_get_runtime}  @value{statusignoremessage} 


@subsection SCSCP_ro_set_message
@deftypefn {Library Function} int SCSCP_ro_set_message ( SCSCP_returnoptions* @var{options}, const char *@var{buffer}, SCSCP_status* @var{status} )
@end deftypefn

This function sets the information message, with the value @var{buffer}, of the options of the procedure return. This information message is defined as the symbol @code{info_message} of the OpenMath Content Dictionary @code{scscp1}. The argument @var{buffer} can't be NULL and won't be duplicated by this function. So @var{buffer} can't be destroyed until the function @code{SCSCP_ro_clear} is called on the object @var{options}.
 
@funcfailssetstatus{SCSCP_ro_set_message} @value{statusignoremessage} 


@subsection SCSCP_ro_get_message
@deftypefn {Library Function} int SCSCP_ro_get_message ( SCSCP_returnoptions* @var{options}, const char **@var{buffer}, SCSCP_status* @var{status} )
@end deftypefn

This function returns, in the argument @var{buffer}, the information message of the options of the procedure return. This information message is defined as the symbol @code{info_message} of the OpenMath Content Dictionary @code{scscp1}. The argument @var{buffer} mustn't be NULL. The returned string mustn't be modified.
 
@funcfailssetstatus{SCSCP_ro_get_message} @value{statusignoremessage} 



@c %-----------------------
@node  XML parsing functions, Remote objects functions, Procedure return options functions , @value{LIBRARYCNAME} Interface
@section XML parsing functions

The following functions are useful to parse incoming messages after reading the header of the message with the functions @code{SCSCP_sc_callrecvheader} or @code{SCSCP_ss_callrecvheader}. The following example prints each node and attribute of a XML tree.

@cartouche
@example
void printelements(SCSCP_xmlnodeptr node, int tab)
@{
   SCSCP_xmlattrptr attr;
   const char *name;
   const char *value;
   int j;
 
   while (node!=NULL)
   @{
      for(j=0; j<tab; j++) putchar(' ');
      printf ("node : '%s'\n",SCSCP_xmlnode_getname(node));
  
      for (attr = SCSCP_xmlnode_getattr(node); 
           attr!=NULL; 
           attr = SCSCP_xmlattr_getnext(attr))
      @{
         SCSCP_xmlattr_getvalue(attr, &name, &value);
         for(j=0; j<tab+1; j++) putchar(' ');
         printf ("attribute : '%s '  = '%s'\n",name, value);
      @}
      printelements(SCSCP_xmlnode_getchild(node),tab+4);
      node = SCSCP_xmlnode_getnext(node);
   @} 
@}
@end example
@end cartouche

@subsection SCSCP_xmlnode_getnext
@deftypefn {Library Function} SCSCP_xmlnodeptr SCSCP_xmlnode_getnext ( SCSCP_xmlnodeptr @var{curnode} )
@end deftypefn
This function returns a pointer to the next node. If @var{curnode} is the last element, this function returns @code{NULL}.

@subsection SCSCP_xmlnode_getname
@deftypefn {Library Function} {const char*} SCSCP_xmlnode_getname ( SCSCP_xmlnodeptr @var{curnode} )
@end deftypefn
This function returns the name of the node @var{curnode}.

@subsection SCSCP_xmlnode_getid
@deftypefn {Library Function} const char* SCSCP_xmlnode_getid ( SCSCP_xmlnodeptr @var{curnode} )
@end deftypefn
This function returns the reference id (<OM... id="...">) of the node @var{curnode}. The function returns NULL if the reference id isn't available.

@subsection SCSCP_xmlnode_getchild
@deftypefn {Library Function} SCSCP_xmlnodeptr SCSCP_xmlnode_getchild ( SCSCP_xmlnodeptr @var{curnode} )
@end deftypefn
This function returns the first child of the node @var{curnode}. The function returns NULL if it has no child.

@subsection SCSCP_xmlnode_getcontent
@deftypefn {Library Function} {const char *} SCSCP_xmlnode_getcontent ( SCSCP_xmlnodeptr @var{curnode} )
@end deftypefn
This function returns as a string the content of the node @var{curnode}.

@subsection SCSCP_xmlnode_getattr
@deftypefn {Library Function} SCSCP_xmlattrptr SCSCP_xmlnode_getattr ( SCSCP_xmlnodeptr @var{curnode} )
@end deftypefn
This function returns the first attribute of the node @var{curnode}.


@subsection SCSCP_xmlattr_getnext
@deftypefn {Library Function} SCSCP_xmlattrptr SCSCP_xmlattr_getnext ( SCSCP_xmlattrptr @var{attr} )
@end deftypefn
This function returns a pointer to the next attribute. If @var{attr} is the last attribute, this function returns @code{NULL}.

@subsection SCSCP_xmlattr_getvalue
@deftypefn {Library Function} int SCSCP_xmlattr_getvalue ( SCSCP_xmlattrptr @var{attr}, const char ** @var{name}, const char ** @var{value} )
@end deftypefn
This function returns, in the argument @var{name}, a pointer to the name of the attribute @var{attr} and returns, in the argument @var{value}, a pointer to the value of the attribute @var{attr}.

@value{funcfails}


@c %-----------
@subsection SCSCP_xmlnode_readOMS
@deftypefn {Library Function} int SCSCP_xmlnode_readOMS ( SCSCP_xmlnodeptr* @var{node}, const char ** @var{cdname}, const char ** @var{symbolname} )
@end deftypefn
This function reads an OpenMath symbol and the cd name to @var{cdname} and the name to @var{symbolname}. @var{symbolname} and @var{cdname} mustn't be NULL.

@funcfailsxmlreadOM{an OpenMath symbol}

@c %-----------
@subsection SCSCP_xmlnode_readOMIstr
@deftypefn {Library Function} int SCSCP_xmlnode_readOMIstr ( SCSCP_xmlnodeptr* @var{node}, const char ** @var{value})
@end deftypefn
This function reads an OpenMath integer and  stores it to @var{value}. @var{value} mustn't be NULL.

@funcfailsxmlreadOM{an OpenMath integer}


@c %-----------
@subsection SCSCP_xmlnode_readOMIint
@deftypefn {Library Function} int SCSCP_xmlnode_readOMIint ( SCSCP_xmlnodeptr* @var{node}, int* @var{value})
@end deftypefn
This function reads an OpenMath integer and  store it to @var{value}. 

@funcfailsxmlreadOM{an OpenMath integer}


@c %-----------
@subsection SCSCP_xmlnode_readOMFstr
@deftypefn {Library Function} int SCSCP_xmlnode_readOMFstr ( SCSCP_xmlnodeptr* @var{node}, const char ** @var{value}, int * @var{base})
@end deftypefn
This function reads an OpenMath floating-point number and stores it to @var{value}. It stores to @var{base} the base used to represent the floating-point number (16 for "hex", 10 for "dec"). @var{value} and @var{base} mustn't be NULL.

@funcfailsxmlreadOM{an OpenMath floating-point}

@c %-----------
@subsection SCSCP_xmlnode_readOMFdouble
@deftypefn {Library Function} int SCSCP_xmlnode_readOMFdouble ( SCSCP_xmlnodeptr* @var{node}, double* @var{value})
@end deftypefn
This function reads an OpenMath floating-point number and stores it to @var{value}. @var{value} mustn't be NULL.

@funcfailsxmlreadOM{an OpenMath floating-point}

@c %-----------
@subsection SCSCP_xmlnode_readOMSTR
@deftypefn {Library Function} int SCSCP_xmlnode_readOMSTR ( SCSCP_xmlnodeptr* @var{node}, const char ** @var{value})
@end deftypefn
This function reads an OpenMath string and  store it to @var{value}. @var{value} mustn't be NULL.

@funcfailsxmlreadOM{an OpenMath string}

@c %-----------
@subsection SCSCP_xmlnode_readOMR
@deftypefn {Library Function} int SCSCP_xmlnode_readOMR ( SCSCP_xmlnodeptr* @var{node}, const char ** @var{value})
@end deftypefn
This function reads an OpenMath reference and stores it to @var{value}. @var{value} mustn't be NULL.

@funcfailsxmlreadOM{an OpenMath reference}

@c %-----------
@subsection SCSCP_xmlnode_readOMV
@deftypefn {Library Function} int SCSCP_xmlnode_readOMV ( SCSCP_xmlnodeptr* @var{node}, const char ** @var{value})
@end deftypefn
This function reads an OpenMath variable and stores it to @var{value}. @var{value} mustn't be NULL.

@funcfailsxmlreadOM{an OpenMath variable}

@c %-----------
@subsection SCSCP_xmlnode_readpairOMSOMSTR
@deftypefn {Library Function} int SCSCP_xmlnode_readpairOMSOMSTR ( SCSCP_xmlnodeptr* @var{node}, const char *@var{cdname}, const char *@var{symbolname}, const char **@var{buffer})
@end deftypefn
This function reads an OpenMath symbol and an OpenMath string. It checks that the symbol has the same symbol name and cd name as the arguments @var{symbolname} and @var{cdname}. It stores the OpenMath string to @var{value}.  @var{cdname}, @var{symbolname} and @var{value} mustn't be NULL.

@funcfailsxmlreadOM{OpenMath symbol and an OpenMath string}


@c %-----------------------
@node  Remote objects functions, Miscellaneous functions, XML parsing functions,  @value{LIBRARYCNAME} Interface
@section Remote objects functions

@subsection SCSCP_sc_remoteobjectstoresessionhook
@deftypefn {Library Function} int SCSCP_sc_remoteobjectstoresessionhook ( SCSCP_socketclient* @var{client}, int (*@var{callbackwriteargs})(SCSCP_io* stream, void *param, SCSCP_status* status), void* @var{param}, char ** @var{cookiename}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} sends a "procedure call" message  to store an object on the server. This object will be usable in the remainder of the current SCSCP session. The object is written by the callback function @var{callbackwriteargs}. The function @var{callbackwriteargs} must use the functions @code{SCSCP_io_writexxx}, such as @code{SCSCP_io_writeOMSTR}, to write data which are sent to the SCSCP server.
A connection must be previously opened with @code{SCSCP_sc_connect} before preforming this call. 

The argument @var{param} is a pointer which is provided to  the @var{callbackwriteargs} to exchange information. This pointer and its content isn't modified by @code{SCSCP_sc_remoteobjectstoresessionhook}.  

On exit, the argument @var{cookiename} contains the name of the Openmath reference returned by the server. This string must be freed by the system call @code{free}.

@funcfailssetstatus{SCSCP_sc_remoteobjectstoresessionhook} @value{statusignoremessage} 

@c %-----------------------------
@subsection SCSCP_sc_remoteobjectstorepersistenthook
@deftypefn {Library Function} int SCSCP_sc_remoteobjectstorepersistenthook ( SCSCP_socketclient* @var{client}, int (*@var{callbackwriteargs})(SCSCP_io* stream, void *param, SCSCP_status* status), void* @var{param}, char ** @var{cookiename}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} sends a "procedure call" message  to store an object on the server. This object will be usable from different SCSCP session. The object is written by the callback function @var{callbackwriteargs}. The function @var{callbackwriteargs} must use the functions @code{SCSCP_io_writexxx}, such as @code{SCSCP_io_writeOMSTR}, to write data which are sent to the SCSCP server.
A connection must be previously opened with @code{SCSCP_sc_connect} before preforming this call. 

The argument @var{param} is a pointer which is provided to  the @var{callbackwriteargs} to exchange information. This pointer and its content isn't modified by @code{SCSCP_sc_remoteobjectstorepersistenthook}.  

On exit, the argument @var{cookiename} contains the name of the Openmath reference returned by the server. This string must be freed by the system call @code{free}.

@funcfailssetstatus{SCSCP_sc_remoteobjectstorepersistenthook} @value{statusignoremessage} 

@c %-----------------------------
@subsection SCSCP_sc_remoteobjectretrievexmlnode
@deftypefn {Library Function} int SCSCP_sc_remoteobjectretrievexmlnode ( SCSCP_socketclient* @var{client}, const char *@var{cookiename}, SCSCP_xmlnodeptr* @var{node}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} sends a "procedure call" message  to retrieve the value of an remote object @var{cookiename} from the server. A connection must be previously opened with @code{SCSCP_sc_connect} before preforming this call. 
This function returns, in the argument @var{node}, a pointer to this OpenMath object.

@funcfailssetstatus{SCSCP_sc_remoteobjectretrievexmlnode} @value{statusignoremessage} 

@c %-----------------------------
@subsection SCSCP_sc_remoteobjectretrievestr
@deftypefn {Library Function} int SCSCP_sc_remoteobjectretrievestr ( SCSCP_socketclient* @var{client}, const char *@var{cookiename}, char** @var{openmathbuffer}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} sends a "procedure call" message  to retrieve the value of an remote object @var{cookiename} from the server. A connection must be previously opened with @code{SCSCP_sc_connect} before preforming this call. 

This function returns, in the argument @var{openmathbuffer}, a string of this OpenMath object. This string must be freed by the system call @code{free}.

@funcfailssetstatus{SCSCP_sc_remoteobjectretrievestr} @value{statusignoremessage} 

@c %-----------------------------
@subsection SCSCP_sc_remoteobjectunbind
@deftypefn {Library Function} int SCSCP_sc_remoteobjectunbind ( SCSCP_socketclient* @var{client}, const char *@var{cookiename}, SCSCP_status* @var{status})
@end deftypefn

The @var{client} sends a "procedure call" message  to remove the remote object @var{cookiename} from the server. A connection must be previously opened with @code{SCSCP_sc_connect} before preforming this call. 

@funcfailssetstatus{SCSCP_sc_remoteobjectunbind} @value{statusignoremessage} 

@c %-----------------------
@node  Miscellaneous functions, , Remote objects functions,  @value{LIBRARYCNAME} Interface
@section Miscellaneous functions

@subsection SCSCP_get_libversionstr
@deftypefn {Library Function} const char* SCSCP_get_libversionstr (void)
@end deftypefn

Return the @value{LIBRARYNAME} version, as a null-terminated string. 

@subsection SCSCP_get_libversionnum
@deftypefn {Library Function} void SCSCP_get_libversionnum (unsigned int *@var{major}, unsigned  int *@var{minor}, unsigned  int *@var{patch})
@end deftypefn

Return the @value{LIBRARYNAME} version as unsigned values. On exit, @var{major} contains the major revision, @var{minor} contains the minor revision and @var{patch} the patch level revision. 

@subsection SCSCP_CHECK_LIBVERSION
@deftypefn {Library Function} int SCSCP_CHECK_LIBVERSION ()
@end deftypefn

Verify that the @value{LIBRARYNAME} versions are consistent.

It verifies that the version of the @value{LIBRARYNAME} with which an application was compiled 
matches the version of the @value{LIBRARYNAME} against which the application is currently linked.

This function is defined as a macro and returns an integer of type int. 

On exit, it returns 
@itemize
@item 0 if the version of the library are not compatible,
@item 1 if the version of the library are compatible and are exactly the same.
@item 2 if the version of the library are compatible and are not exactly the same.
@end itemize

@c %----------------------------------------------------------------------------
@node Design a SCSCP C server, Design a SCSCP C client, @value{LIBRARYCNAME} Interface, Top
@chapter Design a SCSCP C server

The file @file{examples/decodeserver.c} shows the server which decodes each node of the OpenMath expression received from the client. It sends an answer to the client depending on the call options.

@sp 1
A simple SCSCP server could be done with the following operations. This server supports the scscp versions "1.3" and "1.5beta".

@itemize
@item Initialize the server
@example 
SCSCP_socketserver server;
SCSCP_status status = SCSCP_STATUS_INITIALIZER;

SCSCP_ss_init(&server, &status, "MYCAS", "1.0", "myid",
              SCSCP_PROTOCOL_VERSION_1_3, 
              "1.5beta", 
              NULL); 
@end example

@item Listen for incoming client
@example
SCSCP_ss_listen(&client, SCSCP_PROTOCOL_DEFAULTPORT, 0, &status);
@end example

@item Loop over new clients
@example
SCSCP_incomingclient incomingclient;

while (SCSCP_ss_acceptclient(&server, &incomingclient, &status))
@{
@end example

@itemize
@item Receive the "procedure call" message : 2 solutions

@example
SCSCP_calloptions calloptions;
SCSCP_returnoptions returnoptions;
SCSCP_msgtype msgtype;

SCSCP_co_init(&calloptions, status);
SCSCP_ro_init(&returnopt, status);
@end example

@itemize
@item solution 1 : read the header and decode each node of the openmath stream
@example
SCSCP_ss_callrecvheader(&incomingclient, &calloptions,
                        &msgtype, &status);  

SCSCP_xmlnodeptr ptrnode;
ptrnode = SCSCP_ss_getxmlnode(&incomingclient, &status);
@end example

@item solution 2 : read the header and store the content in a string buffer
@example
char *openmathbuffer;
SCSCP_ss_callrecvstr(&incomingclient, &calloptions, &msgtype, 
                     &openmathbuffer, &status); 
@end example
@end itemize

@item Send the answer : procedure completed or terminated ?
@itemize
@item Send a "procedure completed" message
@example
const char *openmathanswer="<OM...>";
SCSCP_ss_sendcompletedstr(&incomingclient, &returnopt,
                          openmathanswer, &status); 
@end example
@item Send a "procedure terminated" message
@example
const char *messageerror="can't store an object";
SCSCP_ss_sendterminatedstr(&incomingclient, &returnopt,
               "sccsp1", "error_system_specific", 
               messageerror, &status); 
@end example
@end itemize

@item clear the options object
@example
SCSCP_co_clear(&options, status);
SCSCP_ro_clear(&returnopt, status);
@end example
@end itemize

@item Close the connection
@example
  SCSCP_ss_closeincoming(&incomingclient, &status);
@}
@end example


@item Stop to listen for incoming clients
@example
SCSCP_ss_close(&server, &status);
@end example
@item Clear the server
@example
SCSCP_ss_clear(&server, &status);
@end example

@end itemize



@c %----------------------------------------------------------------------------
@node Design a SCSCP C client, @value{LIBRARYCXXNAME} Interface, Design a SCSCP C server, Top
@chapter Design a SCSCP C client


The file @file{examples/simplestclient.c} shows the simplest client which stores the value 6177887 on the server and prints the answer of the server.

The file @file{examples/decodeclient.c} shows the client which decodes each node of the OpenMath expression received from the server.

@sp 1

A simple SCSCP client could be done with the following operations. This simple client will connect with the SCSCP server located on "localhost" and listening on port 26133. 

@itemize
@item Initialize the client
@example 
SCSCP_socketclient client;
SCSCP_status status = SCSCP_STATUS_INITIALIZER;

SCSCP_sc_init(&client, &status, SCSCP_PROTOCOL_VERSION_1_3, NULL); 
@end example

@item Open the Connection
@example
SCSCP_sc_connect(&client, "localhost", 
                 SCSCP_PROTOCOL_DEFAULTPORT, &status);
@end example

@item Send a procedure call
@example
SCSCP_calloptions calloptions;
SCSCP_co_init(&calloptions, status);
SCSCP_sc_callsendstr(&client, &calloptions,
    "<OMA><OMS cd=\"scscp2\" name=\"get_allowed_heads\" /></OMA>",
    &status); 
@end example

@item Receive the answer of the procedure call : 2 solutions
@itemize
@item solution 1 : read the header and decode each node of the openmath stream
@example
SCSCP_msgtype msgtype;
SCSCP_returnoptions options;
SCSCP_ro_init(&options, status); 
SCSCP_sc_callrecvheader(client, &options, &msgtype, 
                        &status);
if (msgtype==SCSCP_msgtype_ProcedureTerminated)
@{
    char *messagebuffer;
    char *cdname;
    char *symbolname;
    SCSCP_sc_callrecvterminated(client, &cdname, &symbolname, 
                                &messagebuffer, status);           
 
@}
@end example

@item solution 2 : read the header and store the content in a string buffer
@example
SCSCP_msgtype msgtype;
SCSCP_returnoptions options;
char *buffer;
SCSCP_ro_init(&options, status); 
SCSCP_sc_callrecvstr(client, &options, &msgtype, 
                     &buffer, &status);
@end example
@end itemize

@item Close the connection
@example
SCSCP_sc_close(&client,&status);
@end example
@item Clear the client
@example
SCSCP_sc_clear(&client,&status);
@end example

@end itemize

@c %----------------------------------------------------------------------------
@c %----------------------------------------------------------------------------
@node @value{LIBRARYCXXNAME} Interface , Design a SCSCP C++ server, Design a SCSCP C client, Top
@chapter @value{LIBRARYCXXNAME} Interface

@menu
* Server  ::
* IncomingClient ::
* Client  ::
* Procedure call   ::
* Stream ::
* Exception  ::
* OpenMath objects ::
@end menu

All C++ functions and class are grouped in the namespace @code{SCSCP}.

@c %----------------------------------------------------------------------------
@node Server, IncomingClient, , @value{LIBRARYCXXNAME} Interface
@section Server

@c %-----------------------
@subsection Constructor
@deftypefn Constructor {} Server (const char* @var{servicename}, const char* @var{serviceversion}, const char* @var{serviceid}) throw(Exception)
It initializes the SCSCP server with the default versions (@code{SCSCP_PROTOCOL_VERSION_1_3} and @code{SCSCP_PROTOCOL_VERSION_1_2}) of SCSCP protocol that could be negotiated. 

The arguments @var{servicename}, @var{serviceversion} and @var{serviceid} are used as the value of the attribute @code{service_name}, @code{service_version} and @code{service_id} of the @i{Connection Initiation Message}.
@end deftypefn

@deftypefn Destructor {} ~Server (void)
If the server was listening on a port, the method @code{Server::close} is called before clearing the object. It destroys the SCSCP server.
@end deftypefn
 
@c %-----------------------
@subsection listen
@deftypemethod Server int listen (int @var{port}=SCSCP_PROTOCOL_DEFAULTPORT) throw(Exception)
It creates an internal queue for the incoming connections and starts to listen on the @var{port} of "localhost". If the @var{port} isn't available, it retries with the next port until it finds an available port.

@funcxxfailssetstatus{listen}
@end deftypemethod


@c %-----------------------
@subsection close
@deftypemethod Server int close () throw(Exception)
It terminates to listen for the incoming connections. 

@funcxxfailssetstatus{close}
@end deftypemethod

@c %-----------------------
@subsection eof
@deftypemethod Server  bool eof () const
It returns true if the connection is closed.
@end deftypemethod


@c %-----------------------
@subsection acceptclient
@deftypemethod Server IncomingClient* acceptclient ()  throw ()
It extracts the first connection request on the queue of pending connections. If no pending connections are present on the queue, it blocks the caller until a connection is present.

After the @i{Connection Initiation}, the server returns an object to manage future exchanged messages.

After the transactions, the returned pointer must be deleted to close the connection and release the memory.

@funcxxfailssetstatus{acceptclient}
@end deftypemethod

The following example shows how to implement the main loop of the SCSCP C++ server. 
@cartouche
@example
 SCSCP::Server server("MYCAS","1","myid");
 SCSCP::IncomingClient *incomingclient;
 
 /*listen on the default port */
 server.listen(); 
 
 while ((incomingclient=server.acceptclient())!=NULL)
 @{
    ... process incoming messages ...
   
    delete incomingclient;
 @}

 /* stop the server */
 server.close();
@end example
@end cartouche



@c %----------------------------------------------------------------------------
@node IncomingClient, Client, Server,  @value{LIBRARYCXXNAME} Interface
@section IncomingClient

The class @code{IncomingClient} handles a connection on the SCSCP server side. So on the server side, several instances of that class could exist at the same time to handle connection from different clients. That class is only instanciated by the function @code{Server::acceptclient()}.  

On the server side, the "Procedure Call" request are handled by an instance of @code{Server::Computation}.

@c %-----------------------
@subsection Destructor
@deftypefn Destructor {} ~IncomingClient (void)
If a connection with a client was already opened, the connection is closed with the client.
@end deftypefn

@c %-----------------------
@subsection eof
@deftypemethod Client  bool eof () const
It returns true if the connection is closed.
@end deftypemethod


@c %----------------------------------------------------------------------------
@node Client, Procedure call, IncomingClient,  @value{LIBRARYCXXNAME} Interface
@section Client

The class @code{Client} handles the connection on the SCSCP client side.
After a connection is initialized, the procedure call could be performed using an instance of the class @code{Client::Computation} (@pxref{Procedure call}).

@c %-----------------------
@subsection Constructor
@deftypefn Constructor {} Client (void) throw(Exception)
It initializes the SCSCP client with the default version (@code{SCSCP_PROTOCOL_VERSION_1_3} and @code{SCSCP_PROTOCOL_VERSION_1_2}) of SCSCP protocol that could be negotiated.

During the negotiation with the server, the client will choose the first version, that the server supports too,
 in the following order : @code{SCSCP_PROTOCOL_VERSION_1_3}, and @code{SCSCP_PROTOCOL_VERSION_1_2}.
@end deftypefn

@deftypefn Destructor {} ~Client (void)
If a connection was already opened, the method @code{Client::close} is called before clearing the object. It destroys the SCSCP client.
@end deftypefn

@c %-----------------------
@subsection connect
@deftypemethod Client int connect (const char *@var{machine}, int @var{port}=SCSCP_PROTOCOL_DEFAULTPORT) throw(Exception)
It tries to connect to the SCSCP server which is running on the computer @var{machine} and is listening on the port @var{port}. 

@var{machine} could be any string but it must resolved as an IP address. Its value could be  "localhost" if the SCSCP server runs on the same computer.

In most of the case, the default value @var{SCSCP_PROTOCOL_DEFAULTPORT} should be used for the port number.

@funcxxfailssetstatus{connect}

@end deftypemethod

@c %-----------------------
@subsection close
@deftypemethod Client int close () throw(Exception)
It closes a connection previously opened by the client with the method @code{Client::connect}.
@funcxxfailssetstatus{close}
@end deftypemethod

@c %-----------------------
@subsection eof
@deftypemethod Client  bool eof () const
It returns true if the connection is closed.
@end deftypemethod



@c %----------------------------------------------------------------------------
@node Procedure call, Stream, Client,   @value{LIBRARYCXXNAME} Interface
@section Procedure call

The procedure calls are managed on the client side by a instance of the class @code{Client::Computation}.
The procedure calls are managed on the server side by a instance of the class @code{Server::Computation}.
The class @code{Client::Computation} and @code{Server::Computation} derivate from @code{ProcedureCall} and inherit of all public methods of that class.

@c %-----------------------
@subsection ProcedureCall

This class should not be instantiated by the application. Only the @code{Client::Computation} and @code{Server::Computation} should be instantiated. This class provides methods to access the call options or return options of a procedure call. 

@c %-----------------------
@subsubsection ProcedureCall Constructor
@deftypefn Constructor {} ProcedureCall (Client& @var{session})
It initializes the procedure call. It generates and sets the call identifier of the options of the procedure call. This call identifier is defined as the symbol @code{call_id} of the OpenMath Content Dictionary @code{scscp1}. The call identifier is prefixed by @code{libSCSCP:}.

@end deftypefn

@deftypefn Destructor {} ~ProcedureCall (void)
It destroys the procedure call.
@end deftypefn


@c %-----------------------
@subsubsection set_runtimelimit
@deftypemethod ProcedureCall int set_runtimelimit (size_t @var{time})

This function sets the amount of time in milliseconds, with the value @var{time},  that the SCSCP server should spend on this call. This runtime limit is defined by the symbol @code{option_runtime} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcxxfailsnoexcept{set_runtimelimit} 
@end deftypemethod


@c %-----------------------
@subsubsection get_runtimelimit
@deftypemethod ProcedureCall int get_runtimelimit (size_t& @var{time})

This function returns, in the argument @var{time}, the amount of time in milliseconds  that the server should spend on this call. This amount of time is defined as the symbol @code{option_runtime} of the OpenMath Content Dictionary @code{scscp1}. If the amount of time isn't available (not supplied by the server), the function fails.

@funcxxfailsnoexcept{get_runtimelimit}  
@end deftypemethod


@c %-----------------------
@subsubsection set_minmemory
@deftypemethod ProcedureCall int set_minmemory (size_t @var{memsize})

This function sets the minimum amount of memory in bytes, with the value @var{memsize}, that the server should use on this call. This memory limit is defined by the symbol @code{option_min_memory} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcxxfailsnoexcept{set_minmemory} 
@end deftypemethod

@c %-----------------------
@subsubsection get_minmemory
@deftypemethod ProcedureCall int get_minmemory (size_t& @var{memsize})

This function returns, in the argument @var{memsize}, the minimum amount of memory in bytes that the server should use on this call. This amount of memory is defined as the symbol @code{option_min_memory} of the OpenMath Content Dictionary @code{scscp1}. If the amount of memory isn't available (not supplied by the server), the function fails.

@funcxxfailsnoexcept{get_minmemory}
@end deftypemethod

@c %-----------------------
@subsubsection set_maxmemory
@deftypemethod ProcedureCall int set_maxmemory (size_t @var{memsize})

This function sets the maximum amount of memory in bytes, with the value @var{memsize},  that the SCSCP server should use on this call. This memory limit is defined by the symbol @code{option_max_memory} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcxxfailsnoexcept{set_maxmemory}
@end deftypemethod


@c %-----------------------
@subsubsection get_maxmemory
@deftypemethod ProcedureCall int get_maxmemory (size_t& @var{memsize})

This function returns, in the argument @var{memsize}, the maximum amount of memory in bytes that the server should use on this call. This amount of memory is defined as the symbol @code{option_max_memory} of the OpenMath Content Dictionary @code{scscp1}. If the amount of memory isn't available (not supplied by the server), the function fails.

@funcxxfailsnoexcept{get_maxmemory} 
@end deftypemethod

@c %-----------------------
@subsubsection set_debuglevel
@deftypemethod ProcedureCall int set_debuglevel (int @var{debuglevel})

This function sets the debug level, with the value @var{debuglevel}, that the client is interested. This debug level is defined by the symbol @code{option_debuglevel} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcxxfailsnoexcept{set_debuglevel}
@end deftypemethod


@c %-----------------------
@subsubsection get_debuglevel
@deftypemethod ProcedureCall int get_debuglevel (int& @var{debuglevel})

This function returns, in the argument @var{debuglevel}, the debug level that the client is interested. This debug level is defined as the symbol @code{option_max_memory} of the OpenMath Content Dictionary @code{scscp1}. If the debug level isn't available (not supplied by the server), the function fails and returns 0.

@funcxxfailsnoexcept{get_debuglevel}
@end deftypemethod

@c %-----------------------
@subsubsection set_runtime
@deftypemethod ProcedureCall int set_runtime (size_t @var{time})

This function sets the amount of time in milliseconds, with the value @var{time}, that the server spent on this call. This amount of time is defined as the symbol @code{info_runtime} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcxxfailsnoexcept{set_runtime} 
@end deftypemethod

@c %-----------------------
@subsubsection get_runtime
@deftypemethod ProcedureCall int get_runtime (size_t& @var{time})

This function returns, in the argument @var{time}, the amount of time in milliseconds  that the server spent on this call. This amount of time is defined as the symbol @code{info_runtime} of the OpenMath Content Dictionary @code{scscp1}. If the amount of time isn't available (not supplied by the server), the function fails.

@funcxxfailsnoexcept{get_runtime} 
@end deftypemethod

@c %-----------------------
@subsubsection set_memory
@deftypemethod ProcedureCall int set_memory (size_t @var{memsize})

This function sets the amount of memory in bytes, with the value @var{memsize},  that the server used on this call. This amount of memory is defined as the symbol @code{info_memory} of the OpenMath Content Dictionary @code{scscp1}.
 
@funcxxfailsnoexcept{set_memory} 
@end deftypemethod

@c %-----------------------
@subsubsection get_memory
@deftypemethod ProcedureCall int get_memory (size_t& @var{memsize})

This function returns, in the argument @var{memsize}, the amount of memory in bytes that the server used for this call. This amount of memory is defined as the symbol @code{info_memory} of the OpenMath Content Dictionary @code{scscp1}. If the amount of memory isn't available (not supplied by the server), the function fails.

@funcxxfailsnoexcept{get_runtime}
@end deftypemethod

@c %-----------------------
@subsubsection set_message
@deftypemethod ProcedureCall int set_message ( const char *@var{buffer})

This function sets the information message, with the value @var{buffer}, of the options of the procedure return. This information message is defined as the symbol @code{info_message} of the OpenMath Content Dictionary @code{scscp1}. The argument @var{buffer} can't be NULL and won't be duplicated by this function. So @var{buffer} can't be destroyed until the instance of the object is destroyed.
 
@funcxxfailsnoexcept{set_message}
@end deftypemethod

@c %-----------------------
@subsubsection  get_message
@deftypemethod ProcedureCall int get_message (const char *&@var{buffer})

This function returns, in the argument @var{buffer}, the information message of the options of the procedure return. This information message is defined as the symbol @code{info_message} of the OpenMath Content Dictionary @code{scscp1}. The returned string mustn't be modified.
 
@funcxxfailsnoexcept{get_message} 
@end deftypemethod

@c %-----------------------
@subsubsection set_encodingtype
@deftypemethod ProcedureCall int set_encodingtype (SCSCP_encodingtype @var{encodingtype})

This function sets the current encoding of the OpenMath objects used by the SCSCP server or the client, to send the data. The provided Openmath buffers, such as for the call @code{sendstr}, and the streams operations must use the same encoding.

The default encoding for the SCSCP client and server is the @code{SCSCP_encodingtype_XML}. 

@funcxxfailsnoexcept{set_encodingtype}
@end deftypemethod


@c %-----------------------
@subsubsection get_encodingtype
@deftypemethod ProcedureCall int get_encodingtype (SCSCP_encodingtype& @var{encodingtype})

This function returns, in the argument @var{encodingtype}, the current encoding of the OpenMath objects used by the SCSCP server or the client to send the data.

@funcxxfailsnoexcept{get_encodingtype}
@end deftypemethod

@c %-----------------------
@subsubsection get_returntype
@deftypemethod ProcedureCall int get_returntype (SCSCP_option_return& @var{returntype})

This function returns, in the argument @var{returntype}, the return type of the "procedure call" message that the server should send. The possible value of @var{returntype} are described in the function  @code{SCSCP_co_set_returntype}.

If the return type isn't available (not supplied by the client), the function fails.

@funcxxfailsnoexcept{get_returntype}
@end deftypemethod

@c %-----------------------
@subsubsection get_callid
@deftypemethod ProcedureCall int get_callid (const char*& @var{callid})

This function returns, in the argument @var{callid}, the call id of the procedure call. The returned string mustn't be modified.

@funcxxfailsnoexcept{get_callid}
@end deftypemethod


@c %-----------------------
@subsection Client::Computation

@c %-----------------------
@subsubsection Client::Computation Constructor
@deftypefn Constructor {} Client::Computation (Client& @var{session}) : public ProcedureCall
It initializes the procedure call on the client side. It generates and sets the call identifier of the options of the procedure call. This call identifier is defined as the symbol @code{call_id} of the OpenMath Content Dictionary @code{scscp1}. The call identifier is prefixed by @code{libSCSCP:}.

@end deftypefn

@deftypefn Destructor {} ~Client::Computation (void)
It destroys the procedure call on the client side.
@end deftypefn

@c %-----------------------
@subsubsection send
@deftypemethod Client::Computation int send (const char *@var{openmathbuffer}, size_t @var{lenbuffer}, SCSCP_option_return @var{returntype})

The client sends a "procedure call" message to the SCSCP server with the options specified before. The server will return a result (object, cookie, nothing) depending on the value  @var{returntype}. The array @var{openmathbuffer} is the argument of the procedure call and must be a valid OpenMath Application object with the same encoding as the instance. @var{lenbuffer} specifies the number of valid bytes in the array @var{openmathbuffer}. 

@funcxxfailssetstatus{send}
@end deftypemethod

@deftypemethod Client::Computation int send (SCSCP_option_return @var{returntype}, std::ostream *& @var{outstream}) throw (Exception) 

The client prepares a "procedure call" message to the SCSCP server with the options specified before. The server will return a result (object, cookie, nothing) depending on the value @var{returntype}. 

The OpenMath data must be written to the returned stream @var{outstream}. This stream only accepts  data  already encoded in the OpenMath format. The application is responsible to encode data in the same encoding as specified by @code{get_encodingtype}.

The written data must be an OpenMath Application object. So it must start with @code{<OMA>} and finish with @code{</OMA>} if the XML encoding is used.

The "procedure call" message must be completed with a call to @code{finish()} or discarded with a call to @code{discard()}. These functions will delete the pointer @var{outstream}.

@funcxxfailssetstatus{send}


The following example sends the "Procedure Call" message in order to compute 10! .
@example
Client::Computation mytask(client);
std::ostream* mypstream;
mytask.send(SCSCP_option_return_object, mystream);
*mystream << "<OMA>";
*mystream << "<OMS cd=\"integer1\" name=\"factorial\" />";
*mystream << "<OMI>10</OMI>";
*mystream << "</OMA>";
mytask.finish();
@end example

@end deftypemethod

@deftypemethod Client::Computation int send (SCSCP_option_return @var{returntype}, Ounfstream*& @var{outstream}) throw (Exception) 

The client prepares a "procedure call" message to the SCSCP server with the options specified before. The server will return a result (object, cookie, nothing) depending on the value @var{returntype}. 

The data must be written to the returned stream @var{outstream}. The data will be converted to the OpenMath encoding using the encoding specified by @code{get_encodingtype}.

The written data must be an OpenMath Application object. So it must start with @code{beginOMA()} and finish with @code{endOMA()}.

The "procedure call" message must be completed with a call to @code{finish()} or discarded with a call to @code{discard()}. These functions will delete the pointer @var{outstream}.

@funcxxfailssetstatus{send}

The following example sends the "Procedure Call" message in order to compute 10! .
@example
Client::Computation mytask(client);
Ounfstream *mystream;
mytask.send(SCSCP_option_return_object, mystream);
*mystream << beginOMA;
*mystream << OMS("integer1", "factorial") << 10;
*mystream << endOMA;
mytask.finish();
@end example
@end deftypemethod

@c %-----------------------
@subsubsection recv
@deftypemethod Client::Computation int recv (SCSCP_msgtype& @var{msgtype}, char*& @var{openmathbuffer}, size_t& @var{lenbuffer})

The @var{client} waits for the answer of a "procedure call" message from the server. It reads the attribute, the type and the content of the message returned by the server in response of a procedure call. 

On exit, the argument @var{msgtype} contains the message type returned by the server.  

On exit, the argument @var{openmathbuffer} contains the content of the message returned by the server.  This array must be freed by the system call @code{free}. @var{lenbuffer} contains the number of valid bytes in the array @var{openmathbuffer}.

@funcxxfailssetstatus{recv}
@end deftypemethod


@deftypemethod Client::Computation int recv (SCSCP_msgtype& @var{msgtype}, Iunfstream* &@var{stream}) throw (Exception) 

The @var{client} waits for the answer of a "procedure call" message from the server. It reads the attribute, the type and the content of the message returned by the server in response of a procedure call. 

On exit, the argument @var{msgtype} contains the message type returned by the server.  

On exit, the argument @var{stream} contains a pointer to a stream. It allows to parse the input stream. This pointer is valid until to the next call to @code{recv} or @code{send}.

@funcxxfailssetstatus{recv}
@end deftypemethod


@c %-----------------------
@subsubsection discard
@deftypemethod Client::Computation int discard (void)  throw (Exception) 

It discards the "Procedure call" message previously created with @code{send}. The end of the message isn't sent to the server. So the server won't process this procedure call.  

The stream, returned by the function @code{send},  must not be longer used after that call. 

@funcxxfailssetstatus{discard}
@end deftypemethod


@c %-----------------------
@subsubsection finish
@deftypemethod Client::Computation int finish (void)  throw (Exception) 
It completes the "Procedure call" message previously created with @code{send}. The end of the message is sent to the server. So the server will process it.  

The stream, returned by the function @code{send}, must not be longer used after that call. 

@funcxxfailssetstatus{finish}
@end deftypemethod


@c %-----------------------
@subsection Server::Computation

@c %-----------------------
@subsubsection Server::Computation Constructor
@deftypefn Constructor {} Server::Computation (IncomingClient& @var{session}) : public ProcedureCall
It initializes the instance to handle the procedure call on the server side.  

@end deftypefn

@deftypefn Destructor {} ~Server::Computation (void)
It destroys the instance to handle the procedure call on the server side.
@end deftypefn

@c %-----------------------
@subsubsection recv
@deftypemethod Client::Computation int recv (SCSCP_msgtype& @var{msgtype}, char*& @var{openmathbuffer}, size_t& @var{lenbuffer}) throw (Exception)

It waits for an incoming message. When a new message is available, then it reads the attribute, the type and the content of the message sent by the client @var{incomingclient}. 

On exit, the argument @var{msgtype} must be @code{SCSCP_msgtype_ProcedureCall} or @code{SCSCP_msgtype_Interrupt}. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument @var{msgtype} is @code{SCSCP_msgtype_Interrupt}, the call identifier of the interrupted procedure call could be retrieved with a call to @code{get_callid()}.

On exit, the argument @var{openmathbuffer} contains the content of the message sent by the client.  This string must be freed by the system call @code{free}.

@funcxxfailssetstatus{recv}
@end deftypemethod

@deftypemethod Client::Computation int recv (SCSCP_msgtype& @var{msgtype}, Iunfstream*& @var{stream}) throw (Exception)

It waits for an incoming message. When a new message is available, then it reads the attribute, the type and the content of the message sent by the client @var{incomingclient}. 

On exit, the argument @var{msgtype} must be @code{SCSCP_msgtype_ProcedureCall} or @code{SCSCP_msgtype_Interrupt}. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument @var{msgtype} is @code{SCSCP_msgtype_Interrupt}, the call identifier of the interrupted procedure call could be retrieved with a call to @code{get_callid()}.

On exit, the argument @var{stream} contains a pointer to a stream. It allows to parse the input stream. This pointer is valid until to the next call to @code{recv} or @code{send}.

@funcxxfailssetstatus{recv}
@end deftypemethod


@c %-----------------------
@subsubsection sendcompleted

These methods allow to send a "procedure completed" message to the client.

@deftypemethod Client::Computation int sendcompleted (const char* @var{openmathbuffer}=NULL, size_t @var{lenbuffer}=0) throw (Exception)

It sends a "procedure completed" message using an openmath buffer to the client with the options specified before.  The array @var{openmathbuffer} is the argument of the procedure call and must be a valid OpenMath object with the same encoding as the instance. If the anwser is empty, @var{openmathbuffer} could be NULL. @var{lenbuffer} specifies the number of valid bytes in the array @var{openmathbuffer}. 

@funcxxfailssetstatus{sendcompleted}
@end deftypemethod

@deftypemethod Client::Computation int sendcompleted (std::ostream *& @var{outstream}) throw (Exception)

The server prepares to send a "procedure completed" message using an openmath buffer to the client with the options specified before.  

The OpenMath data must be written to the returned stream @var{outstream}. This stream only accepts  data  already encoded in the OpenMath format. The application is responsible to encode data in the same encoding as specified by @code{get_encodingtype}.

The written data must be an OpenMath object.

The answer must be completed with a call to @code{finish()}. That function will delete the pointer @var{outstream}.

@funcxxfailssetstatus{sendcompleted}
@end deftypemethod


@deftypemethod Server::Computation int sendcompleted (Ounfstream*& @var{outstream}) throw (Exception) 

The server prepares to send a "procedure completed" message using an openmath buffer to the client with the options specified before.  

The data must be written to the returned stream @var{outstream}. The data will be converted to the OpenMath encoding using the encoding specified by @code{get_encodingtype}.

The written data must be an OpenMath object.

The answer must be completed with a call to @code{finish()}. That function will delete the pointer @var{outstream}.

@funcxxfailssetstatus{send}
@end deftypemethod

 
@c %-----------------------
@subsubsection sendterminated

That method allows to send a "procedure terminated" message to the client.

@deftypemethod Client::Computation int sendterminated (const char * @var{cdname}, const char * @var{symbolname}, const char * @var{message}) throw (Exception)

It sends a "procedure terminated" message to the SCSCP client  with the options specified before. The symbol of the OpenMath Error is defined by  its name @var{symbolname} and its CD @var{cdname}. @var{message} is the message that will be inserted in a OMSTR OpenMath object.

@funcxxfailssetstatus{sendterminated}
@end deftypemethod


@c %-----------------------
@subsubsection finish
@deftypemethod Server::Computation int finish (void)  throw (Exception) 
It completes the answer previously created with @code{sendcompleted}. The end of the message is sent to the client. So the client will process it.  

The stream, returned by the function @code{sendcompleted}, must not be longer used after that call. 

@funcxxfailssetstatus{finish}
@end deftypemethod


@c %----------------------------------------------------------------------------
@node Stream, Exception, Procedure call,    @value{LIBRARYCXXNAME} Interface
@section Stream

@subsection Ounfstream

This output stream handles the writing of the basic C data-types, such as int, double, ....  It supports also the manipulators to build complex OpenMath objects. It encodes in binary or XML the OpenMath objects according to the current encoding of the stream.
The following example buids the OpenMath Object, corresponding to 1+n^2 :

@example
Ounfstream& stream =...
stream<< beginOMA << OMS("arith1","plus")
   stream<< 1 
   stream<< beginOMA <<OMS("arith1","power") << OMV("n") << 2 << endOMA
stream<<endOMA;
@end example

@c %-----------------------
@subsubsection beginOMA
@deftypemethod Ounfstream&  beginOMA (Ounfstream&) throw (Exception)
It writes the beginning of the structured Open Math object @code{<OMA>} to the stream @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection endOMA
@deftypemethod Ounfstream&  beginOMA (Ounfstream&) throw (Exception)
It writes the end of the structured Open Math object @code{</OMA>} to the @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection beginOMATP
@deftypemethod Ounfstream&  beginOMATP (Ounfstream&) throw (Exception)
It writes the beginning of the structured Open Math object @code{<OMATP>} to the stream @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection endOMATP
@deftypemethod Ounfstream&  endOMATP (Ounfstream&) throw (Exception)
It writes the end of the structured Open Math object @code{</OMATP>} to the @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection beginOMATTR
@deftypemethod Ounfstream&  beginOMATTR (Ounfstream&) throw (Exception)
It writes the beginning of the structured Open Math object @code{<OMATTR>} to the stream @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection endOMATTR
@deftypemethod Ounfstream&  endOMATTR (Ounfstream&) throw (Exception)
It writes the end of the structured Open Math object @code{</OMATTR>} to the @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection beginOME
@deftypemethod Ounfstream&  beginOME (Ounfstream&) throw (Exception)
It writes the beginning of the structured Open Math object @code{<OME>} to the stream @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection endOME
@deftypemethod Ounfstream&  endOME (Ounfstream&) throw (Exception)
It writes the end of the structured Open Math object @code{</OME>} to the @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection beginOMOBJ
@deftypemethod Ounfstream&  beginOMOBJ (Ounfstream&) throw (Exception)
It writes the beginning of the structured Open Math object @code{<OMOBJ>} to the stream @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection endOMOBJ
@deftypemethod Ounfstream&  endOMOBJ (Ounfstream&) throw (Exception)
It writes the end of the structured Open Math object @code{</OMOBJ>} to the @var{stream}.

@funcstreamxxfailssetstatus{}
@end deftypemethod

@c %-----------------------
@subsubsection operator<<
@deftypeop operator<< Ounfstream Ounfstream& operator << (Ounfstream& @var{out}, int @var{x}) throw (Exception)
It writes @var{x} to the stream @code{out} as the basic OpenMath object @code{<OMI>...</OMI>} according to the current encoding.

@funcstreamxxfailssetstatus{}
@end deftypeop

@deftypeop operator<< Ounfstream Ounfstream& operator << (Ounfstream& @var{out}, double @var{x}) throw (Exception)
It writes @var{x} to the stream @code{out} as the basic OpenMath object @code{<OMF dec="..."/>} according to the current encoding.

@funcstreamxxfailssetstatus{}
@end deftypeop

@deftypeop operator<< Ounfstream Ounfstream& operator << (Ounfstream& @var{out}, const char * @var{str}) throw (Exception)
It writes the C-style string @var{str} to the stream @code{out} as the basic OpenMath object @code{<OMSTR>...</OMSTR>} according to the current encoding.

@funcstreamxxfailssetstatus{}
@end deftypeop

@deftypeop operator<< Ounfstream Ounfstream& operator << (Ounfstream& @var{out}, OMF @var{x})  throw (Exception)
It writes the OpenMath float @var{x} to the stream @code{out} according to the current encoding.

@funcstreamxxfailssetstatus{}
@end deftypeop


@deftypeop operator<< Ounfstream Ounfstream& operator << (Ounfstream& @var{out}, OMI @var{x})  throw (Exception)
It writes the OpenMath integer @var{x} to the stream @code{out} according to the current encoding.

@funcstreamxxfailssetstatus{}
@end deftypeop

@deftypeop operator<< Ounfstream Ounfstream& operator << (Ounfstream& @var{out}, OMR @var{x})  throw (Exception)
It writes the OpenMath reference @var{x} to the stream @code{out} according to the current encoding.

@funcstreamxxfailssetstatus{}
@end deftypeop

@deftypeop operator<< Ounfstream Ounfstream& operator << (Ounfstream& @var{out}, OMS @var{x}) throw (Exception)
It writes the OpenMath symbol @var{x} to the stream @code{out} according to the current encoding.

@funcstreamxxfailssetstatus{}
@end deftypeop

@deftypeop operator<< Ounfstream Ounfstream& operator << (Ounfstream& @var{out}, OMV @var{x}) throw (Exception)
It writes the OpenMath variable @var{x} to the stream @code{out} according to the current encoding.

@funcstreamxxfailssetstatus{}
@end deftypeop



@c %-----------------------
@subsection Iunfstream

@c %-----------------------
@subsubsection omtype

This type is an enumeration of the possible values of the node.

The possible values are
@table @samp
@item  SCSCP_omtype_OMI
OpenMath integer.

@item  SCSCP_omtype_OMF
OpenMath IEEE floating point number.

@item  SCSCP_omtype_OMV
OpenMath variable.

@item  SCSCP_omtype_OMS
OpenMath symbol.

@item  SCSCP_omtype_OMSTR
OpenMath string.

@item  SCSCP_omtype_OMB
OpenMath byte array.

@item  SCSCP_omtype_OMFOREIGN
OpenMath foreign.

@item  SCSCP_omtype_OMA
OpenMath application.

@item  SCSCP_omtype_OMBIND
OpenMath binding.

@item  SCSCP_omtype_OMATTR
OpenMath attribution.

@item  SCSCP_omtype_OME
OpenMath error.

@item  SCSCP_omtype_OMATP
OpenMath attribute pair.

@item  SCSCP_omtype_OMOBJ
OpenMath object.

@item  SCSCP_omtype_OMBVAR
OpenMath variables used in binding.

@item  SCSCP_omtype_OMR
OpenMath reference.

@item  SCSCP_omtype_CONTENT
content node.

@end table


@c %-----------------------
@subsubsection iterator_attr

This type in an iterator on the attributes of the Openmath elements. it could be used in a similar as iteraor of the STL.

@cartouche
@example
  Iunfstream& stream = .... ;
  
  for (Iunfstream::iterator_attr attr = stream.get_attr(); 
       attr.end() ;
       ++attr)
  @{
     PRINTAB(tab+1); 
     cout <<"attribute : '" << attr.get_name() <<"'  = '"
          << attr.get_value() <<"'"<<endl;
  @}

@end example
@end cartouche


This type defines the following methods.

@deftypemethod Iunfstream::iterator_attr  bool end () const
It returns true if no more attributes are available, otherwise it returns false.
@end deftypemethod

@deftypemethod Iunfstream::iterator_attr  void operator++ ()
It goes to the next attributes.
@end deftypemethod

@deftypemethod Iunfstream::iterator_attr  const char *get_name () const
It returns the name of the current attribute.
@end deftypemethod

@deftypemethod Iunfstream::iterator_attr  const char *get_value () const
It returns the value of the current attribute.
@end deftypemethod



@c %-----------------------
@subsubsection eof
@deftypemethod Iunfstream  bool eof () const
It returns true if no more nodes are available in the stream.
@end deftypemethod


@c %-----------------------
@subsubsection get_attr
@deftypemethod Iunfstream  Iunfstream::iterator_attr get_attr () 
It returns an iterator on the attributes of the nodes.
@end deftypemethod

@c %-----------------------
@subsubsection get_type
@deftypemethod Iunfstream  Iunfstream::omtype get_type () const
It returns as an enumeration the current node, .e.g, SCSCP_omtype_OMA for an OpenMath Application.
It could return SCSCP_omtype_CONTENT if the node contains only a content.
@end deftypemethod


@c %-----------------------
@subsubsection get_typename
@deftypemethod Iunfstream  const char* get_typename () const
It returns as a C-style string the name of the current node, .e.g, "OMA" for an OpenMath Application.
It could return NULL if the node contains only a content.
@end deftypemethod


@c %-----------------------
@subsubsection get_content
@deftypemethod Iunfstream  const char* get_content () const
It returns as a C-style string the content of the current node.
It returns NULL if the content of the OpenMath object is empty.
@end deftypemethod


@c %-----------------------
@subsubsection beginOM
@deftypemethod Iunfstream  Iunfstream beginOM () 
It returns a stream to parse the children nodes of the derived OpenMath objects.
@end deftypemethod

@c %-----------------------
@subsubsection operator>>
@deftypeop operator>> Iunfstream Iunfstream& operator >> (int& @var{x})  throw (Exception)
It reads an OpenMath object from the stream and converts it to the integer @var{x}. If this OpenMath object can't be converted to a floating-point, an exception is raised. 

@funcstreamxxfailssetstatus{}
@end deftypeop   

@deftypeop operator>> Iunfstream Iunfstream& operator >> (double& @var{x})  throw (Exception)
It reads an OpenMath object from the stream and converts it to the floating-point @var{x}. If this OpenMath object can't be converted to a floating-point, an exception is raised. 

@funcstreamxxfailssetstatus{}
@end deftypeop   

@deftypeop operator>> Iunfstream Iunfstream& operator >> (const char*& @var{x})  throw (Exception)
It reads an OpenMath string from the stream and store it to @var{x}. If this OpenMath object can't be converted to a string, an exception is raised. 

@funcstreamxxfailssetstatus{}
@end deftypeop   

@deftypeop operator>> Iunfstream Iunfstream& operator >> (OMF @var{x})  throw (Exception)
It reads the OpenMath float @var{x} from the stream.

@funcstreamxxfailssetstatus{}
@end deftypeop   

@deftypeop operator>> Iunfstream Iunfstream& operator >> (OMI @var{x})  throw (Exception)
It reads the OpenMath integer @var{x} from the stream.

@funcstreamxxfailssetstatus{}
@end deftypeop   

@deftypeop operator>> Iunfstream Iunfstream& operator >> (OMR @var{x})  throw (Exception)
It reads the OpenMath reference @var{x} from the stream.

@funcstreamxxfailssetstatus{}
@end deftypeop   

@deftypeop operator>> Iunfstream Iunfstream& operator >> (OMS @var{x})  throw (Exception)
It reads the OpenMath symbol @var{x} from the stream.

@funcstreamxxfailssetstatus{}
@end deftypeop   

@deftypeop operator>> Iunfstream Iunfstream& operator >> (OMV @var{x})  throw (Exception)
It reads the OpenMath variable @var{x} from the stream.

@funcstreamxxfailssetstatus{}
@end deftypeop   
 
  
@c %----------------------------------------------------------------------------
@node Exception , OpenMath objects, Stream,   @value{LIBRARYCXXNAME} Interface
@section Exception

On errors, the C++ functions raise an exception of type @code{Exception} which derivates from the STL @code{std::exception}.

@c %-----------------------
@subsection Constructor
@deftypefn Constructor {} Exception (const SCSCP_status* status) : public std::exception

It initializes the SCSCP exception wit the specified status information.
@end deftypefn

@deftypefn Destructor {} ~Exception (void)
It destroys the exception.
@end deftypefn

@c %-----------------------
@subsection what
@deftypemethod Exception const char * what () const throw()
It returns a C-style character string describing the general cause of the current error. 
@end deftypemethod

@c %----------------------------------------------------------------------------
@node OpenMath objects, , Exception,   @value{LIBRARYCXXNAME} Interface
@section OpenMath objects

These OpenMath objects are usefull to perform the input or output from/to the stream. All these OpenMath objects derivate from the base class @code{OMBase}.

The C-style string accepted by their constructor aren't duplicated and must exist during the life of the instance of the object.

The method @code{beginOM} is a common method for derived OpenMath object, such as OMA, OME, ....

@c %-----------------------
@subsection OMBase
@deftypemethod OMBase const char * get_id () const
It returns the reference id (<OM .... id="...">) of the Openmath object. It may return NULL if the reference id of the object is unset.
@end deftypemethod

@c %-----------------------
@subsection OMA
@deftypefn Constructor {} OMA (const char *@var{id}=NULL)
It creates the OpenMath application with the reference @var{id}.  paramid
@end deftypefn

@deftypemethod OMA  Iunfstream beginOM () 
It returns a stream to parse the children nodes of the derived OpenMath objects.
@end deftypemethod

@c %-----------------------
@subsection OMBIND
@deftypefn Constructor {} OMBIND (const char *@var{id}=NULL)
It creates the OpenMath binding with the reference @var{id}.  paramid
@end deftypefn

@deftypemethod OMBIND  Iunfstream beginOM () 
It returns a stream to parse the children nodes of the derived OpenMath objects.
@end deftypemethod

@c %-----------------------
@subsection OME
@deftypefn Constructor {} OME (const char *@var{id}=NULL)
It creates the OpenMath error with the reference @var{id}.  paramid
@end deftypefn

@deftypemethod OME  Iunfstream beginOM () 
It returns a stream to parse the children nodes of the derived OpenMath objects.
@end deftypemethod

@c %-----------------------
@subsection OMF
@deftypefn Constructor {} OMF (const char* @var{value}, const char *@var{id}=NULL)
It creates the OpenMath float with the @var{value} and the reference @var{id}.  paramid
The C-style string @var{href} isn't duplicated. @var{value} must be in base 10.
@end deftypefn

@deftypemethod OMF const char * get_value () const
This function returns the value of the Openmath float.
@end deftypemethod

@deftypemethod OMF int get_base () const
This function returns the base number of the Openmath float.
@end deftypemethod

@c %-----------------------
@subsection OMI
@deftypefn Constructor {} OMI (const char* @var{value}, const char *@var{id}=NULL)
It creates the OpenMath integer with the @var{value} and the reference @var{id}.  paramid
The C-style string @var{href} isn't duplicated. @var{value} must be in base 10.
@end deftypefn

@deftypemethod OMI const char * get_value () const
This function returns the value of the Openmath integer.
@end deftypemethod


@c %-----------------------
@subsection OMR
@deftypefn Constructor {} OMR (const char* @var{href})
It creates the OpenMath reference @var{href}. The C-style string @var{href} isn't duplicated.
@end deftypefn

@deftypemethod OMR const char * get_reference () const
This function returns the value of the Openmath reference.
@end deftypemethod

@c %-----------------------
@subsection OMS
@deftypefn Constructor {} OMS (const char* @var{cdname}, const char* @var{symbolname}, const char *@var{id}=NULL)
It creates the OpenMath symbol @var{symbolname} of the Content Dictionary @var{cdname}. The C-style strings @var{cdname} and @var{symbolname} aren't duplicated. @paramid
@end deftypefn

@deftypemethod OMS const char * get_cdname () const
This function returns the cd name of the Openmath symbol.
@end deftypemethod

@deftypemethod OMS const char * get_symbolname () const
This function returns the symbol name of the Openmath symbol.
@end deftypemethod


@c %-----------------------
@subsection OMV
@deftypefn Constructor {} OMV (const char* @var{name}, const char *@var{id}=NULL)
It creates the OpenMath variable @var{name}. The C-style string @var{name} isn't duplicated. @paramid
@end deftypefn

@deftypemethod OMS const char * get_name () const
This function returns the name of the Openmath variable.
@end deftypemethod


@c %----------------------------------------------------------------------------
@node Design a SCSCP C++ server, Design a SCSCP C++ client, @value{LIBRARYCXXNAME} Interface, Top
@chapter Design a SCSCP C++ server

The file @file{examples/decodeserverxx.cpp} shows the server which decodes each node of the OpenMath expression received from the client. It sends an answer to the client depending on the call options.

@sp 1
A simple SCSCP C++ server could be done with the following operations. This server supports the scscp versions "1.3".

@itemize
using namespace SCSCP;

@item Initialize the server
@example 
Server server("MYCAS", "1.0", "myid");
@end example

@item Listen for incoming client
@example
server.listen();
@end example

@item Loop over new clients
@example
IncomingClient *incomingclient;

while ((incomingclient=server.acceptclient())!=NULL)
@{
@end example

@itemize
@item Receive the "procedure call" message : 2 solutions

@example
Server::Computation mytask(incomingclient);
@end example

@itemize
@item solution 1 : read the header and parse the openmath stream
@example
Iunfstream *mystream;
mytask.recv(msgtype, mystream);  
...
@end example

@item solution 2 : read the header and store the content in a string buffer
@example
char *openmathbuffer;
mytask.recv(msgtype, openmathbuffer, lenbuffer); 
....
free(openmathbuffer);
@end example
@end itemize

@item Send the answer : procedure completed or terminated ?
@itemize
@item  Send a "procedure completed" message : 3 solutions
@itemize
@item solution 1 : C-style byte array using the XML or binary encoding  (C-string is XML)
@example
  const char *answer="<OMI>10</OMI>";
  mytask.sendcompleted(answer, ::strlen(answer)); 
@end example
@item solution 2 : STL ostream using the XML encoding only
@example
 std::ostream*& stream;
 mytask.sendcompleted(stream);
 *stream << "<OMI>10</OMI>";
 mytask.finish();
@end example

@item solution 3 : unformatted stream using the XML or binary encoding
@example
 Ounfstream* stream;
 mytask.sendcompleted(stream);
 *stream << 10;
 mytask.finish();
@end example
@end itemize

@item Send a "procedure terminated" message
@example
const char *messageerror="can't store an object";
mytask.sendterminated("sccsp1", "error_system_specific", 
                      messageerror); 
@end example
@end itemize

@end itemize

@item Close the connection
@example
  delete incomingclient;
@}
@end example


@item Stop to listen for incoming clients
@example
server.close();
@end example

@end itemize




@c %----------------------------------------------------------------------------
@node Design a SCSCP C++ client, References, Design a SCSCP C++ server, Top
@chapter Design a SCSCP C++ client

The file @file{examples/simplestclientxx.cpp} shows the simplest client which stores the value 6177887 on the server using the C-byte array and prints the answer of the server.

The file @file{examples/simplestclientstreamfmtxx.cpp} shows the simplest client which stores the value 6177887 on the server using the STL ostream  and prints the answer of the server.

The file @file{examples/simplestclientstreamunfxx.cpp} shows the simplest client which stores the value 435 on the server using the unformatted stream and prints the answer of the server.

@sp 1

A simple SCSCP client could be done with the following operations. This simple client will connect with the SCSCP server located on "localhost" and listening on port 26133. 

@itemize
@item Initialize the client
@example 
SCSCP::Client client;
@end example

@item Open the Connection
@example
client.connect("localhost");
@end example

@item Send a procedure call : 3 solutions
Client::Computation mytask(myclient);
@itemize
@item solution 1 : C-style byte array using the XML or binary encoding  (C-string is XML)
@example
 const char *cmd = "<OMA><OMS cd=\"scscp2\" 
                          name=\"get_allowed_heads\"/></OMA>";

 mytask.send(cmd, ::strlen(cmd), SCSCP_option_return_object);
@end example
@item solution 2 : STL ostream using the XML encoding only
@example
 std::ostream*& stream;
 mytask.send(SCSCP_option_return_object, stream);
 *stream << "<OMA>";
 *stream << "<OMS cd=\"scscp2\" name=\"get_allowed_heads\"/>
 *stream << </OMA>";
 mytask.finish();
@end example

@item solution 3 : unformatted stream using the XML or binary encoding
@example
 Ounfstream* stream;
 mytask.send(SCSCP_option_return_object, stream);
 *stream << beginOMA;
 *stream << OMS("scscp2","get_allowed_heads");
 *stream << endOMA;
 mytask.finish();
@end example
@end itemize

@item Receive the answer of the procedure call : 2 solutions
@itemize
@item solution 1 : read the header and parse the openmath stream
@example
Iunfstream *mystream;
mytask.recv(msgtype, mystream);  
...
@end example
@item solution 2 : read the header and store the content in a string buffer
@example
 char *buffer;
 size_t lenbuffer;
 SCSCP_msgtype msgtype;
 mytask.recv(msgtype, buffer,lenbuffer);
@end example
@end itemize

@item Close the connection
@example
 client.close();
@end example

@end itemize


@c %----------------------------------------------------------------------------
@node References, , Design a SCSCP C++ client, Top
@chapter References

@itemize

@item Symbolic Computation Software Composability Protocol (SCSCP) specification

Version 1.3, 2009

S.Freundt, P.Horn, A.Konovalov, S.Linton, D.Roozemond.

@url{http://www.symcomp.org/scscp}


@item  OpenMath content dictionary  scscp1

D. Roozemond

@url{http://www.win.tue.nl/SCIEnce/cds/scscp1.html}


@item  OpenMath content dictionary  scscp2

D. Roozemond

@url{http://www.win.tue.nl/SCIEnce/cds/scscp2.html}


@end itemize


@bye
