/*******************************************************************************
 *	overview.doc	Main overview page for LibBds
 *******************************************************************************
 */
/**
@author Dr Terry Barnaby
@version 3.1.0
@date 2022-11-21

@mainpage

@section Introduction
This documention provides detailed reference information for the BEAM BdsApi software API of the Blacknest Data System (BDS).
The API provides the ability to store and access seismic sensor data and metadata as well as administer the BDS system.
The API is an object orientated API implemented in 'C++' with a number of object classes. It also has bindings for other
languages which include Python and PHP.

The API operates over a network interface using an RPC type mechanism implemented by BEAM's BOAP RPC system.
The BdsApi API makes use of the BEAM Beamlib 'C++' class library for lower level and system independent functionality.
The BEAM Beamlib 'C++' class library provides a small set of low level 'C++' classes for strings, lists and system interface functions.
It also implements the BOAP RPC mechanism used to implement the BdsApi. There is some brief information on the
BEAM class library later on in this page and the API description is available in the Beamlib documentation.

The BDS Python API is built on top of the standard BDS 'C++' API using the SWIG API generator. Thus all of the standard
BDS C++ API documentation applies however there are some differences due to the language facility and syntax differences.
The core difference is when returning data from functions. With C++ you can return data by passing references or pointers to objects.
In Python this is not generally possible and so objects are returned at the left hand side of functions instead.

This is the reference documentation for the BdsApi. An overall API description and programming manual is provided separately in:
<a href='../../BdsDevelopment.pdf'>BdsDevelopment.pdf</a>

@section Overview
The BdsApi has been developed using the BOAP (BEAM Object Access Protocol). This provides a simple
but powerful Object Orientated RPC mechanism using an efficient binary protocol. The BdsApi is written in a high
level interface definition language (IDL). The Beamlib bidl tool generates the client
and server side 'C++' interface and implementation files for the API. These are
then provided as a set of 'C++' header files and a binary library file for the
clients and server programs to link to. The BOAP system employs a simple BOAP name server process
that provides a translation between object names and network IPAddress/Socket numbers.
The BOAP name server runs on the main BDS Server host. More information on the BOAP
system can be found in the Beamlib documentation.

The object orientated BDS API implements a number of data storage classes and three BdsServer interface objects.
The interface objects are:

<ol>
<li><b>Bds::DataAccess</b> BDS Data API: This provides read only access to the data and meta data. It is used by the AutoDRM email and Web systems as well as for user and general program access to the data.</li>
<li><b>Bds::DataAddAccess</b> BDS DataAdd API: This provides read and restricted write access to enable the adding of data to the system. It will not allow deletions of data to be performed. It is designed to be used by manual and automatic data adding programs.</li>
<li><b>Bds::AdminAccess</b> BDS Admin API: This provides full read/write access to the data and meta data as well as administrative configuration information.</li>
</ol>

These access API's are related in that the DataAddAccess API is a subset of the AdminAccess API and the DataAccess API is a subset of the DataAddAccess API.
These API access objects should be consulted to view the functionality provided by the BDS system API's.

This documentation is automatically geneerated from the BDS source code and describes the classes and their member functions. For higher level
information on how to use these please consult the <a href='../../BdsDevelopment.pdf'>BdsDevelopment.pdf</a> document..

@section ExamplesCpp C++ Examples
There are some examples of client applications using the BdsApi in the
<b>bdsExamples</b> directory of the source code.
Some simple Data Access client examples are listed below:
@include bdsDataClient1.cpp

@include bdsDataClient2.cpp

@include bdsMetaData1.cpp


@section ExamplesPython Python Examples
There are some examples of client applications using the BdsApi in the
<b>bdsExamples</b> directory of the source code.
Some simple Data Access client examples are listed below:

@include bdsDataClient1.py

@include bdsDataClient2.py

@include bdsMetaData1.py

*/