\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename gamalib-api.info
@settitle GNU GaMa API
@setchapternewpage odd
@c %**end of header

@ifinfo
This file documents API to GNU GaMa classses and functions

Copyright 2001 Ales Cepek

Permission is granted to make and distribute verbatim copies of this
document, provided the copyright notice and this permission notice are
preserved on all copies.

@end ifinfo

@c  This title page illustrates only one of the
@c  two methods of forming a title page.

@titlepage
@title GNU GaMa API
@author Ales Cepek

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2001 Ales Cepek

Permission is granted to make and distribute verbatim copies of this
document, provided the copyright notice and this permission notice are
preserved on all copies.

@end titlepage
     
@node Top, C++, (dir), (dir)
@comment  node-name,  next,  previous,  up
@ifinfo
@chapter  C++/C API to GaMaLib 
@end ifinfo

In the this first draft, only esential GaMaLib classes and functions
referenced through C API are mentioned.  In the description of C API
functions you can find only a list of function names; a simple demo
program gamalib/c/api/capi_demo.c tries to demonstrate their usage.

@menu
* C++ ::                        
* C API::                       

@detailmenu
 --- The Detailed Node Listing ---

GaMaLib C++ functions and classes

* Exception::                   
* class LocalNetwork::          
* class GKFparser::             

class Exception.

* Exception(const string&);::   

class GKFparser

* GKFparser()::                 
* ~GKFparser()::                
* xml_parse()::                 
* gkf_characterDataHandler::    
* gkf_startElement::            
* gkf_endElement::              

C API for GaMa / GaMaLib

* Initialization::              
* Exceptions::                  
* Local Network::               
* GKF parser::                  

Exceptions

* const char* Cgama_exception();::  
* int Cgama_exception_unknown();::  
* void Cgama_exception_clean();::  

Local Network

* Cgama_LocalNetwork_svd::      
* Cgama_LocalNetwork_gso::      
* Cgama_LocalNetwork_dtor::     
* Cgama_LocalNetwork_algorithm::  

GKF parser

* Cgama_GKF_parser::            
* Cgama_GKF_parser_dtor::       
* Cgama_GKF_parser_parse::      

@end detailmenu
@end menu

@node C++, C API, Top, Top
@comment  node-name,  next,  previous,  up
@chapter GaMaLib C++ functions and classes

In the this first draft, only esential GaMaLib classes and functions
referenced through C API are mentioned here; @pxref{C API}.

@menu
* Exception::                   
* class LocalNetwork::          
* class GKFparser::             
@end menu

@node Exception, class LocalNetwork, C++, C++
@comment  node-name,  next,  previous,  up
@section class Exception.

Class Exception is basic GaMaLib exception class, all other GaMaLib
exception classes are derive from it.


@menu
* Exception(const string&);::   
@end menu

@node Exception(const string&);,  , Exception, Exception
@comment  node-name,  next,  previous,  up
@subsection Exception::Exception(const std::string&);

Constructor.

@c #########################################################################

@node class LocalNetwork, class GKFparser, Exception, C++
@comment  node-name,  next,  previous,  up
@section class LocalNetwork

Description of C++ class LocalNetwork should come here ...


@c #########################################################################

@node class GKFparser,  , class LocalNetwork, C++
@comment  node-name,  next,  previous,  up
@section class GKFparser

@menu
* GKFparser()::                 
* ~GKFparser()::                
* xml_parse()::                 
* gkf_characterDataHandler::    
* gkf_startElement::            
* gkf_endElement::              
@end menu

@node GKFparser(), ~GKFparser(), class GKFparser, class GKFparser
@comment  node-name,  next,  previous,  up
@subsection GKFparser::GKFparser(PointData&, ObservationData&)

GKFparser constructor for the given @code{PointData} and
@code{ObservationData} objects.

@node ~GKFparser(), xml_parse(), GKFparser(), class GKFparser
@comment  node-name,  next,  previous,  up
@subsection GKFparser::~GKFparser()

Destructor.

@node xml_parse(), gkf_characterDataHandler, ~GKFparser(), class GKFparser
@comment  node-name,  next,  previous,  up
@subsection void GKFparser::xml_parse(const char *s, int len, int isFinal)

Parses some input (see @code{expat} function @code{XML_parse}). The last
call must have isfinal true; len may be zero for this call (or any
other).

@node gkf_characterDataHandler, gkf_startElement, xml_parse(), class GKFparser
@comment  node-name,  next,  previous,  up
@subsection int gkf_characterDataHandler(const char* s, int len);

GKFparser set character data handler function.

@node gkf_startElement, gkf_endElement, gkf_characterDataHandler, class GKFparser
@comment  node-name,  next,  previous,  up
@subsection int gkf_startElement(const char *cname, const char **atts);

GKFparser set start element handler function.

@node gkf_endElement,  , gkf_startElement, class GKFparser
@comment  node-name,  next,  previous,  up
@subsection int gkf_endElement(const char * name);

GKFparser set end element handler function.

@c #########################################################################



@c #########################################################################
@c #########################################################################
@c #########################################################################



@node C API,  , C++, Top
@comment  node-name,  next,  previous,  up
@chapter C API for GaMa / GaMaLib

In this chapter C API to essential GaMaLib classes and functions are
descried. To be easily distinguisehed from other C++ GaMaLib names,
all names in C API start with @code{Cgama_}.

GaMa / GaMaLib data objects are represented as @code{void*} when using C
API functions. Constructors return pointers to the created objects, in
other functions, corresponding to C++ methods, pointer @code{void*} is
the first parameter.


@menu
* Initialization::              
* Exceptions::                  
* Local Network::               
* GKF parser::                  
* Formatted output::            
@end menu


@node Initialization, Exceptions, C API, C API
@comment  node-name,  next,  previous,  up
@section Initialization

C API must be initialized by calling function

@example
Cgama_init(0);
@end example

@noindent where argument value selects language; 0 is used for English.


@node Exceptions, Local Network, Initialization, C API
@comment  node-name,  next,  previous,  up
@section Exceptions

GNU GaMa / GaMaLib relies on C++ exceptions for handling errors and
other situations when processing has to be interupted or canceled.  All
calls to GaMaLib C++ (member) functions is thus wraped in a
@code{try-block}. Data odbjects used by C API exception handling
functions are hidden from users (everything is declared in unnamed
namespace), initialization and clean up is done automaticaly.
Information on objects caught by exception handlers is available through
the following C API functions.

@menu
* const char* Cgama_exception();::  
* int Cgama_exception_unknown();::  
* void Cgama_exception_clean();::  
@end menu

@node const char* Cgama_exception();, void Cgama_exception_clean();, Exceptions, Exceptions
@comment  node-name,  next,  previous,  up
@subsection   const char* Cgama_exception();

Returns pointer to GaMaLib exception text or zero if there is no
exception. If an unknown exception is caught (ie exception that is not
derived from GaMaLib::Exceptio), function returns empty string "".


@node void Cgama_exception_clean();, int Cgama_exception_unknown();, const char* Cgama_exception();, Exceptions
@comment  node-name,  next,  previous,  up
@subsection void Cgama_exception_clean();

Clears all information from the last caught exception. If no exception
present, function does nothing.


@node int Cgama_exception_unknown();,  , void Cgama_exception_clean();, Exceptions
@comment  node-name,  next,  previous,  up
@subsection int Cgama_exception_unknown();

Tests if the current exceptions is of unknown type. If the current
exception is not derived from GaMaLib::Exception, function returns 1,
otherwise 0. If no exception has been caught, the return value is 0.

@c #########################################################################

@node Local Network, GKF parser, Exceptions, C API
@comment  node-name,  next,  previous,  up
@section Local Network

For description of C API local network handling functions see
description of corresponding C++ class member functions, @pxref{class
LocalNetwork}.

@menu
* Cgama_LocalNetwork_svd::      
* Cgama_LocalNetwork_gso::      
* Cgama_LocalNetwork_dtor::     
* Cgama_LocalNetwork_algorithm::  
* Cgama_LocalNetwork_set_apriori_m0::  
* Cgama_LocalNetwork_set_conf_pr  ::  
* Cgama_LocalNetwork_set_tol_abs ::  
* Cgama_LocalNetwork_set_type_refsd::  
* Cgama_LocalNetwork_PoindtData_empty::  
* Cgama_LocalNetwork_ObservationData_empty::  
* Cgama_LocalNetwork_refine_approx::  
@end menu

@node Cgama_LocalNetwork_svd, Cgama_LocalNetwork_gso, Local Network, Local Network
@comment  node-name,  next,  previous,  up
@subsection void* Cgama_LocalNetwork_svd();

C API constructor of a local network object using SVD algorithm.

@node Cgama_LocalNetwork_gso, Cgama_LocalNetwork_dtor, Cgama_LocalNetwork_svd, Local Network
@comment  node-name,  next,  previous,  up
@subsection void* Cgama_LocalNetwork_gso();

C API constructor of a local network object using algorithm GSO

@node Cgama_LocalNetwork_dtor, Cgama_LocalNetwork_algorithm, Cgama_LocalNetwork_gso, Local Network
@comment  node-name,  next,  previous,  up
@subsection Cgama_LocalNetwork_dtor(void*);

C API virtual destructor of a local network object.


@node Cgama_LocalNetwork_algorithm, Cgama_LocalNetwork_set_apriori_m0, Cgama_LocalNetwork_dtor, Local Network
@comment  node-name,  next,  previous,  up
@subsection const char* Cgama_LocalNetwork_algorithm(local_network)

Numerical algorithm used in the adjustment.

@node Cgama_LocalNetwork_set_apriori_m0, Cgama_LocalNetwork_set_conf_pr  , Cgama_LocalNetwork_algorithm, Local Network
@comment  node-name,  next,  previous,  up
@subsection void Cgama_LocalNetwork_set_apriori_m0(void*, double);

Set apriori value of standard reference deviation.

@node Cgama_LocalNetwork_set_conf_pr  , Cgama_LocalNetwork_set_tol_abs , Cgama_LocalNetwork_set_apriori_m0, Local Network
@comment  node-name,  next,  previous,  up
@subsection  void Cgama_LocalNetwork_set_conf_pr(void*, double);

Set value of confidence probability.

@node Cgama_LocalNetwork_set_tol_abs , Cgama_LocalNetwork_set_type_refsd, Cgama_LocalNetwork_set_conf_pr  , Local Network
@comment  node-name,  next,  previous,  up
@subsection  void Cgama_LocalNetwork_set_tol_abs(void*, double);

Set value for testing of outlying gross absolute terms.

@node Cgama_LocalNetwork_set_type_refsd, Cgama_LocalNetwork_PoindtData_empty, Cgama_LocalNetwork_set_tol_abs , Local Network
@comment  node-name,  next,  previous,  up
@subsection void Cgama_LocalNetwork_set_type_refsd(void*, int p); 

If value of parameter p is `true', set the type o reference variable
used in adjustment to `apriori'; if p is 'false' set the type to
`aposteriori'.

@node Cgama_LocalNetwork_PoindtData_empty, Cgama_LocalNetwork_ObservationData_empty, Cgama_LocalNetwork_set_type_refsd, Local Network
@comment  node-name,  next,  previous,  up
@subsection int Cgama_LocalNetwork_PoindtData_empty(void*);

True if point data is empty.


@node Cgama_LocalNetwork_ObservationData_empty, Cgama_LocalNetwork_refine_approx, Cgama_LocalNetwork_PoindtData_empty, Local Network
@comment  node-name,  next,  previous,  up
@subsection int Cgama_LocalNetwork_ObservationData_empty(void*);

True if observation data is empty.


@node Cgama_LocalNetwork_refine_approx,  , Cgama_LocalNetwork_ObservationData_empty, Local Network
@comment  node-name,  next,  previous,  up
@subsection void Cgama_LocalNetwork_refine_approx(void* ptr);

Refine approximate coordinates by replacing given valueswith
corresponding adjusted coordinates.

@c #########################################################################


@node GKF parser, Formatted output, Local Network, C API
@comment  node-name,  next,  previous,  up
@section GKF parser

C API interface functions to C++ class GKFparser, @pxref{class GKFparser}.

@menu
* Cgama_GKF_parser::            
* Cgama_GKF_parser_dtor::       
* Cgama_GKF_parser_parse::      
* Cgama_GKF_parser_apriori_m0::  
* Cgama_GKF_parser_conf_pr::    
* Cgama_GKF_parser_tol_abs::    
* Cgama_GKF_parser_m0_apriori::  
* Cgama_GKF_parser_description::  
@end menu

@node Cgama_GKF_parser, Cgama_GKF_parser_dtor, GKF parser, GKF parser
@comment  node-name,  next,  previous,  up
@subsection void* Cgama_GKF_parser(void* local_network);

Creates GKFparser object for a given LocalNetwork object, @pxref{Local
Network}.

@node Cgama_GKF_parser_dtor, Cgama_GKF_parser_parse, Cgama_GKF_parser, GKF parser
@comment  node-name,  next,  previous,  up
@subsection  void Cgama_GKF_parser_dtor(void*);

C API destructor of GKFparser objects.

@node Cgama_GKF_parser_parse, Cgama_GKF_parser_apriori_m0, Cgama_GKF_parser_dtor, GKF parser
@comment  node-name,  next,  previous,  up
@subsection void Cgama_GKF_parser_parse(void*, const char* text, int len, int isfinal)

Parses some input (see @code{expat} function @code{XML_parse}). The last
call must have isfinal true; len may be zero for this call (or any
other).

@node Cgama_GKF_parser_apriori_m0, Cgama_GKF_parser_conf_pr, Cgama_GKF_parser_parse, GKF parser
@comment  node-name,  next,  previous,  up
@subsection double Cgama_GKF_parser_apriori_m0(void*);

Standard reference deviation value.

@node Cgama_GKF_parser_conf_pr, Cgama_GKF_parser_tol_abs, Cgama_GKF_parser_apriori_m0, GKF parser
@comment  node-name,  next,  previous,  up
@subsection double Cgama_GKF_parser_conf_pr(void*);

Confidence probability.

@node Cgama_GKF_parser_tol_abs, Cgama_GKF_parser_m0_apriori, Cgama_GKF_parser_conf_pr, GKF parser
@comment  node-name,  next,  previous,  up
@subsection double Cgama_GKF_parser_tol_abs(void*);

Tolerance for identification of gross absolute terms.

@node Cgama_GKF_parser_m0_apriori, Cgama_GKF_parser_description, Cgama_GKF_parser_tol_abs, GKF parser
@comment  node-name,  next,  previous,  up
@subsection int Cgama_GKF_parser_m0_apriori(void*);

`True' (1) if we work with apriori reference standard deviation in
adjustment; `false' (0) if empirical reference standard deviation is
used.

@node Cgama_GKF_parser_description,  , Cgama_GKF_parser_m0_apriori, GKF parser
@comment  node-name,  next,  previous,  up
@subsection const char* Cgama_GKF_parser_description(void* parser);

Returns network description as a C string. The function calls malloc
for allocating new memory. Allocated memory must be released by calling
the function free from <stdlib.h>

@c #########################################################################

@node Formatted output,  , GKF parser, C API
@comment  node-name,  next,  previous,  up
@section Formatted output

Currently GaMa supports only formatted output into files (or into
C++ standard output streams, @pxref{C++}). One of planned future
enchancements is to add XML output of GaMa adjustment (formatted output
then would be based in it).


@menu
* Cgama_output_file::           
* Cgama_output_file_close::     
* Cgama_gamalib_version::       
* Cgama_of_string::             
* Cgama_of_approximate_coordinates::  
* Cgama_of_network_description::  
* Cgama_of_fixed_points::       
* Cgama_of_adjusted_observations::  
* Cgama_of_adjusted_unknowns::  
* Cgama_of_approximate_coordinates::  
* Cgama_of_error_ellipses::     
* Cgama_of_general_parameters::  
* Cgama_of_outlying_abs_terms::  
* Cgama_of_residuals_observations::  
* Cgama_of_test_linearization::  
@end menu


@node Cgama_output_file, Cgama_output_file_close, Formatted output, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void* Cgama_output_file(void* local_network, const char* file_name);
 
Constructor for C API output file objets.
 
@node Cgama_output_file_close, Cgama_gamalib_version, Cgama_output_file, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_output_file_close(void* object);

Destructor. 

@node Cgama_gamalib_version, Cgama_of_string, Cgama_output_file_close, Formatted output
@comment  node-name,  next,  previous,  up
@subsection const char* Cgama_gamalib_version();

Returns gamalib version string.

@node Cgama_of_string, Cgama_of_approximate_coordinates, Cgama_gamalib_version, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_string(void* object, const char* string);

Writes the given string to C API output file object

@node Cgama_of_approximate_coordinates, Cgama_of_network_description, Cgama_of_string, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_approximate_coordinates(void*);

Computes approximate coordinates and writes results into C API output
file objets.


@node Cgama_of_network_description, Cgama_of_fixed_points, Cgama_of_approximate_coordinates, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_network_description(void*, char* text);

Prints network description into C API ooutput file object. Network
description is supplied as a C string, obtained from the call to
function Capi_GKF_parser_description,
@pxref{Cgama_GKF_parser_description}.


@node Cgama_of_fixed_points, Cgama_of_adjusted_observations, Cgama_of_network_description, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_fixed_points(void*);

Prints review of points with fixed coordinates.

@node Cgama_of_adjusted_observations, Cgama_of_adjusted_unknowns, Cgama_of_fixed_points, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_adjusted_observations(void*);

Prints review of adjusted observations.

@node Cgama_of_adjusted_unknowns, Cgama_of_error_ellipses, Cgama_of_adjusted_observations, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_adjusted_unknowns(void*);

Prints review of adjusted unknowns.

@node Cgama_of_error_ellipses, Cgama_of_general_parameters, Cgama_of_adjusted_unknowns, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_error_ellipses(void*);

Prints information on error ellipses of coordinates of adjusted points.

@node Cgama_of_general_parameters, Cgama_of_outlying_abs_terms, Cgama_of_error_ellipses, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_general_parameters(void*);

Prints general information on the adjustment results.

@node Cgama_of_outlying_abs_terms, Cgama_of_residuals_observations, Cgama_of_general_parameters, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_outlying_abs_terms(void*);

Prints information on huge absolute terms in project equations.

@node Cgama_of_residuals_observations, Cgama_of_test_linearization, Cgama_of_outlying_abs_terms, Formatted output
@comment  node-name,  next,  previous,  up
@subsection void Cgama_of_residuals_observations(void*);

Prints information on adjusted residuals.

@node Cgama_of_test_linearization,  , Cgama_of_residuals_observations, Formatted output
@comment  node-name,  next,  previous,  up
@subsection int Cgama_of_test_linearization(void*);

Returns true if approximate coordinates need refinement, ie if errors
resulting from bad linearization are significant.

@c #########################################################################


@bye








