Commit 9d9253f3 authored by no_author's avatar no_author
Browse files

This commit was manufactured by cvs2svn to create tag 'nmxptool_1_1_4'.

git-svn-id: file:///home/quintiliani/svncopy/nmxptool/tags/nmxptool_1_1_4@403 3cd66e75-5955-46cb-a940-c26e5fc5497d
parent 4e9c38b7
This diff is collapsed.
/*! \file
*
* \brief Nanometrics Protocol Library
*
* Author:
* Matteo Quintiliani
* Istituto Nazionale di Geofisica e Vulcanologia - Italy
* quintiliani@ingv.it
*
* $Id: nmxp.h,v 1.37 2007-09-21 07:02:30 mtheo Exp $
*
*/
/*! \mainpage
*
* \section intro_sec Introduction
*
* This is the documentation for the <i>APIs</i> that implement the <tt>Nanometrics Protocols</tt>.
* They have been developed for interacting with \c NaqsServer and \c DataServer.
*
* The Nanometrics \c NaqsServer provides online access to time-series, serial data, triggers, and state-of-health data via TCP subscription.
*
* The Nanometrics \c DataServer provides local and remote access to nanometrics, serial, and state-of-health data via TCP/IP.
*
* The library offers APIs to:
* \li interact with \c NaqsServer that uses version 1.4 of the <i>Private Data Stream Protocol</i>
* \li interact with \c DataServer that uses version 1.0 of the <i>Nanometrics Data Access Protocol</i>
* \li manage Nanometrics data formats
* \li request, receive and interpret online and offline data
*
* moreover, you can use them to develop software to:
* \li analyze data in realtime (waveforms, triggers, ...)
* \li retrieve and convert on the fly data into the mini-SEED records (optional)
* \li feed SeedLink server (optional)
*
*
* \section dependencies_sec Dependencies
*
* An optional library is needed to allow \c libnmxp to save mini-SEED records:
*
* \li \c libmseed: http://www.iris.edu/manuals/\n
* The Mini-SEED library. A C library framework for manipulating and managing SEED data records.\n
* Author: Chad Trabant, <i>IRIS DMC</i>\n
*
*
* \section install_sec Installation
*
* \c nmxp library has been developed using <i>GNU Build Tools</i> (\c automake, \c autoconf and \c configure script)
* taking in account the POSIX Cross-Platform aspects.
* So you should be able to compile and install it everywhere you can launch the following commands:
*
* <tt>./configure</tt>
*
* <tt>make</tt>
*
* <tt>make install</tt>
*
* Please, refer to the file \b README and \b INSTALL for more details.
*
* \section tools_sec Tools
*
* Inside the distribution is available a tool which is a client that interact with \c NaqsServer and \c DataServer.
*
* \c nmxptool:
* \li implements the <i>Nanometrics Private Data Stream Protocol 1.4</i> and permits to retrieve data in near-realtime.\n
* \li implements the <i>Nanometrics Data Access Protocol 1.0</i> and permits to retrieve backward data.\n
* Please, refer to the \b README file or help <tt>nmxptool --help</tt>.
*
*
* \subsection examples_sec Examples
*
* etc...
*
*
* \section license_sec License
*
* This library is free software; you can redistribute it and/or modify it
* under the terms of the GNU Library General Public License as published by
* the Free Software Foundation; either version 2 of the License, or (at your
* option) any later version.
*
* This library is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE.
*
* See the GNU Library General Public License (GNU-LGPL) for more details.
* File \b COPYING inside this distribution.
* The GNU-LGPL and further information can be found here: http://www.gnu.org/
*
*
* \section about_sec About
*
* Matteo Quintiliani - <i>Istituto Nazionale di Geofisica e Vulcanologia</i> - Italy
*
* Mail bug reports and suggestions to <quintiliani@ingv.it>
*
*/
#ifndef NMXP_H
#define NMXP_H 1
#include "nmxp_base.h"
#include "nmxp_crc32.h"
/*! \brief Flag for buffered packets */
typedef enum {
NMXP_BUFFER_NO = 0,
NMXP_BUFFER_YES = 1
} NMXP_BUFFER_FLAG;
/*! \brief Body of ConnectRequest message*/
typedef struct {
char username[12];
int32_t version;
int32_t connection_time;
int32_t crc32;
} NMXP_CONNECT_REQUEST;
/*! \brief Body of DataRequest message*/
typedef struct {
int32_t chan_key;
int32_t start_time;
int32_t end_time;
} NMXP_DATA_REQUEST;
#define NMXP_MAX_FUNC_PD 10
#define TIME_TOLLERANCE 0.001
typedef struct {
int32_t last_seq_no_sent;
double last_sample_time;
int32_t max_pdlist_items;
double max_tollerable_latency;
int32_t n_pdlist;
NMXP_DATA_PROCESS **pdlist; /* Array for pd queue */
} NMXP_RAW_STREAM_DATA;
/*! \brief Sends the message "Connect" on a socket
*
* \param isock A descriptor referencing the socket.
*
* \retval SOCKET_OK on success
* \retval SOCKET_ERROR on error
*
*/
int nmxp_sendConnect(int isock);
/*! \brief Sends the message "TerminateSubscription" on a socket
*
* \param isock A descriptor referencing the socket.
* \param reason Reason for the shutdown.
* \param message String message. It could be NULL.
*
* \retval SOCKET_OK on success
* \retval SOCKET_ERROR on error
*
*/
int nmxp_sendTerminateSubscription(int isock, NMXP_SHUTDOWN_REASON reason, char *message);
/*! \brief Receive message "NMXP_CHAN_LIST" from a socket
*
* \param isock A descriptor referencing the socket.
* \param[out] pchannelList List of channels. It will need to be freed!
*
* \retval SOCKET_OK on success
* \retval SOCKET_ERROR on error
*
*/
int nmxp_receiveChannelList(int isock, NMXP_CHAN_LIST **pchannelList);
/*! \brief Sends the message "AddTimeSeriesChannels" on a socket
*
* \param isock A descriptor referencing the socket.
* \param channelList List of channel.
* \param shortTermCompletion Short-term-completion time = s, 1<= s <= 300 seconds.
* \param out_format Output format.
* -1 Compressed packets.
* 0 Uncompressed packets.
* 0 < out_format, requested output sample rate.
* \param buffer_flag Server will send or not buffered packets.
*
* \retval SOCKET_OK on success
* \retval SOCKET_ERROR on error
*
*/
int nmxp_sendAddTimeSeriesChannel(int isock, NMXP_CHAN_LIST *channelList, int32_t shortTermCompletion, int32_t out_format, NMXP_BUFFER_FLAG buffer_flag);
/*! \brief Receive Compressed or Decompressed Data message from a socket and launch func_processData() on the extracted data
*
* \param isock A descriptor referencing the socket.
* \param channelList Channel list.
* \param network_code Network code. It can be NULL.
*
* \retval Pointer to the structure NMXP_DATA_PROCESS on success
* \retval NULL on error
*
*/
NMXP_DATA_PROCESS *nmxp_receiveData(int isock, NMXP_CHAN_LIST *channelList, const char *network_code);
/*! \brief Sends the message "ConnectRequest" on a socket
*
* \param isock A descriptor referencing the socket.
* \param naqs_username User name (maximum 11 characters), zero terminated.
* \param naqs_password Password.
* \param connection_time Time that the connection was opened.
*
* \retval SOCKET_OK on success
* \retval SOCKET_ERROR on error
*
*/
int nmxp_sendConnectRequest(int isock, char *naqs_username, char *naqs_password, int32_t connection_time);
/*! \brief Read connection time from a socket
*
* \param isock A descriptor referencing the socket.
* \param[out] connection_time Time in epoch.
*
* \retval SOCKET_OK on success
* \retval SOCKET_ERROR on error
*
*/
int nmxp_readConnectionTime(int isock, int32_t *connection_time);
/*! \brief Wait the message "Ready" from a socket
*
* \param isock A descriptor referencing the socket.
*
* \retval SOCKET_OK on success
* \retval SOCKET_ERROR on error
*
*/
int nmxp_waitReady(int isock);
/*! \brief Sends the message "DataRequest" on a socket
*
* \param isock A descriptor referencing the socket.
* \param key Channel key for which data are requested.
* \param start_time Start time of the interval for which data are requested. Epoch time.
* \param end_time End time of the interval for which data are requested. Epoch time.
*
* \retval SOCKET_OK on success
* \retval SOCKET_ERROR on error
*
*/
int nmxp_sendDataRequest(int isock, int32_t key, int32_t start_time, int32_t end_time);
/*! \brief Get the list of available channels from a server
*
* \param hostname host name
* \param portnum port number
* \param datatype Type of data contained in the channel.
*
* \return Channel list. It will need to be freed.
*
* \warning Returned value will need to be freed.
*
*/
NMXP_CHAN_LIST *nmxp_getAvailableChannelList(char * hostname, int portnum, NMXP_DATATYPE datatype);
/*! \brief Get the list of the start and end time for the available data for each channel.
*
* \param hostname host name
* \param portnum port number
* \param datatype Type of data contained in the channel.
* \param flag_request_channelinfo Request information about Network.
*
* \return Channel list. It will need to be freed.
*
* \warning Returned value will need to be freed.
*
*/
NMXP_META_CHAN_LIST *nmxp_getMetaChannelList(char * hostname, int portnum, NMXP_DATATYPE datatype, int flag_request_channelinfo);
/*! \brief Base function for qsort() in order to sort an array of pointers to pointers to NMXP_DATA_PROCESS
*
* \param a pointer to a pointer to NMXP_DATA_PROCESS
* \param b pointer to a pointer to NMXP_DATA_PROCESS
*/
int nmxp_raw_stream_seq_no_compare(const void *a, const void *b);
/*! \brief Allocate and initialize fields inside a NMXP_RAW_STREAM_DATA structure
*
* \param raw_stream_buffer pointer to NMXP_RAW_STREAM_DATA struct to initialize
* \param max_pdlist_items value of max number of items in array
*
*/
void nmxp_raw_stream_init(NMXP_RAW_STREAM_DATA *raw_stream_buffer, int32_t max_tollerable_latency);
/*! \brief Free fields inside a NMXP_RAW_STREAM_DATA structure
*
* \param raw_stream_buffer pointer to NMXP_RAW_STREAM_DATA struct to initialize
*
*/
void nmxp_raw_stream_free(NMXP_RAW_STREAM_DATA *raw_stream_buffer);
/*! \brief Execute a list of functions on an chronological ordered array of NMXP_DATA_PROCESS structures
*
* \param p pointer to NMXP_RAW_STREAM_DATA
* \param a_pd pointer to NMXP_DATA_PROCESS struct to insert into the array
* \param p_func_pd array of functions to execute on a single item NMXP_DATA_PROCESS
* \param n_func_pd number of functions into the array p_func_pd
*
*/
int nmxp_raw_stream_manage(NMXP_RAW_STREAM_DATA *p, NMXP_DATA_PROCESS *a_pd, int (*p_func_pd[NMXP_MAX_FUNC_PD]) (NMXP_DATA_PROCESS *), int n_func_pd);
/*! \brief Execute a list of functions on remaining NMXP_DATA_PROCESS structures
*
* \param p pointer to NMXP_RAW_STREAM_DATA
* \param p_func_pd array of functions to execute on a single item NMXP_DATA_PROCESS
* \param n_func_pd number of functions into the array p_func_pd
*
*/
int nmxp_raw_stream_manage_flush(NMXP_RAW_STREAM_DATA *p, int (*p_func_pd[NMXP_MAX_FUNC_PD]) (NMXP_DATA_PROCESS *), int n_func_pd);
#endif
/*! \file
*
* \brief Base for Nanometrics Protocol Library
*
* Author:
* Matteo Quintiliani
* Istituto Nazionale di Geofisica e Vulcanologia - Italy
* quintiliani@ingv.it
*
* $Id: nmxp_base.h,v 1.22 2007-09-11 14:06:12 mtheo Exp $
*
*/
#ifndef NMXP_BASE_H
#define NMXP_BASE_H 1
#include "nmxp_data.h"
#include "nmxp_chan.h"
#include "nmxp_log.h"
/*! Maximum time between connection attempts (seconds). */
#define NMXP_SLEEPMAX 60
/*! Return message for succes on socket. */
#define NMXP_SOCKET_OK 0
/*! Return message for error on socket.*/
#define NMXP_SOCKET_ERROR -1
/*! \brief Looks up target host, opens a socket and connects
*
* \param hostname hostname
* \param portNum port number
*
* \retval sd A descriptor referencing the socket.
* \retval -1 "Empty host name", "Cannot lookup host", ...
*
*/
int nmxp_openSocket(char *hostname, int portNum);
/*! \brief Close a socket.
*
* \param isock A descriptor referencing the socket.
*
* \retval 0 Success
* \retval -1 Error
*
*/
int nmxp_closeSocket(int isock);
/*! \brief Sends a buffer on a socket.
*
* \param isock A descriptor referencing the socket.
* \param buffer Data buffer.
* \param length Length in bytes.
*
* \retval NMXP_SOCKET_OK on success
* \retval NMXP_SOCKET_ERROR on error
*
*/
int nmxp_send_ctrl(int isock, void *buffer, int length);
/*! \brief Receives length bytes in a buffer from a socket.
*
* \param isock A descriptor referencing the socket.
* \param[out] buffer Data buffer.
* \param length Length in bytes.
*
* \warning Data buffer it has to be allocated before and big enough to contain length bytes!
*
* \retval NMXP_SOCKET_OK on success
* \retval NMXP_SOCKET_ERROR on error
*
*/
int nmxp_recv_ctrl(int isock, void *buffer, int length);
/*! \brief Sends header of a message.
*
* \param isock A descriptor referencing the socket.
* \param type Type of message within \ref NMXP_MSG_CLIENT.
* \param length Length in bytes.
*
* \retval NMXP_SOCKET_OK on success
* \retval NMXP_SOCKET_ERROR on error
*
*/
int nmxp_sendHeader(int isock, NMXP_MSG_CLIENT type, int32_t length);
/*! \brief Receives header of a message.
*
* \param isock A descriptor referencing the socket.
* \param[out] type Type of message within \ref NMXP_MSG_CLIENT.
* \param[out] length Length in bytes.
*
* \retval NMXP_SOCKET_OK on success
* \retval NMXP_SOCKET_ERROR on error
*
*/
int nmxp_receiveHeader(int isock, NMXP_MSG_SERVER *type, int32_t *length);
/*! \brief Sends header and body of a message.
*
* \param isock A descriptor referencing the socket.
* \param type Type of message within \ref NMXP_MSG_CLIENT.
* \param buffer Data buffer. It could be NULL.
* \param length Length in bytes. It must be greater or equal to zero.
*
* \retval NMXP_SOCKET_OK on success
* \retval NMXP_SOCKET_ERROR on error
*
*/
int nmxp_sendMessage(int isock, NMXP_MSG_CLIENT type, void *buffer, int32_t length);
/*! \brief Receives header and body of a message.
*
* \param isock A descriptor referencing the socket.
* \param[out] type Type of message within \ref NMXP_MSG_SERVER.
* \param[out] buffer Data buffer. It will need to be freed!
* \param[out] length Length in bytes.
*
* \warning buffer will need to be freed!
*
* \retval NMXP_SOCKET_OK on success
* \retval NMXP_SOCKET_ERROR on error
*
*/
int nmxp_receiveMessage(int isock, NMXP_MSG_SERVER *type, void **buffer, int32_t *length);
/*! \brief Process Compressed Data message by function func_processData().
*
* \param buffer_data Pointer to the data buffer containing Compressed Nanometrics packets.
* \param length_data Buffer length in bytes.
* \param channelList Pointer to the Channel List.
* \param network_code Network code. It can be NULL.
*
* \return Return a pointer to static struct NMXP_DATA_PROCESS.
*
*/
NMXP_DATA_PROCESS *nmxp_processCompressedData(char* buffer_data, int length_data, NMXP_CHAN_LIST *channelList, const char *network_code);
/*! \brief Process decompressed Data message by function func_processData().
*
* \param buffer_data Pointer to the data buffer containing Decompressed Nanometrics packets.
* \param length_data Buffer length in bytes.
* \param channelList Pointer to the Channel List.
* \param network_code Network code. It can be NULL.
*
* \return Return a pointer to static struct NMXP_DATA_PROCESS.
*
*/
NMXP_DATA_PROCESS *nmxp_processDecompressedData(char* buffer_data, int length_data, NMXP_CHAN_LIST *channelList, const char *network_code);
#endif
/*! \file
*
* \brief Channels for Nanometrics Protocol Library
*
* Author:
* Matteo Quintiliani
* Istituto Nazionale di Geofisica e Vulcanologia - Italy
* quintiliani@ingv.it
*
* $Id: nmxp_chan.h,v 1.20 2007-09-07 07:08:30 mtheo Exp $
*
*/
#ifndef NMXP_CHAN_H
#define NMXP_CHAN_H 1
#include <stdint.h>
/*! \brief Channel list */
typedef struct NMXP_META_CHAN_LIST {
int32_t key;
char name[12];
int32_t start_time;
int32_t end_time;
char network[12];
struct NMXP_META_CHAN_LIST *next;
} NMXP_META_CHAN_LIST;
typedef enum {
NMXP_META_SORT_KEY = 1,
NMXP_META_SORT_NAME,
NMXP_META_SORT_START_TIME,
NMXP_META_SORT_END_TIME
} NMXP_META_CHAN_LIST_SORT_TYPE;
/*! \brief The key/name info for one channel */
typedef struct {
int32_t key;
char name[12];
} NMXP_CHAN_KEY;
/*! \brief Max number of channels */
#define MAX_N_CHAN 1000
/*! \brief Channel list */
typedef struct {
int32_t number;
NMXP_CHAN_KEY channel[MAX_N_CHAN];
} NMXP_CHAN_LIST;
/*! \brief Precis Channel item */
typedef struct {
int32_t key;
char name[12];
int32_t start_time;
int32_t end_time;
} NMXP_CHAN_PRECISITEM;
/*! \brief Precis Channel list */
typedef struct {
int32_t number;
NMXP_CHAN_PRECISITEM channel[MAX_N_CHAN];
} NMXP_CHAN_PRECISLIST;
/*! \brief Type of Data */
typedef enum {
NMXP_DATA_TIMESERIES = 1,
NMXP_DATA_SOH = 2,
NMXP_DATA_TRANSERIAL = 6
} NMXP_DATATYPE;
/*! \brief Precis list request body */
typedef struct {
int32_t instr_id;
NMXP_DATATYPE datatype;
int32_t type_of_channel;
} NMXP_MSGBODY_PRECISLISTREQUEST;
/*! \brief Channel info request body */
typedef struct {
int32_t key;
char name[12];
char network[12];
} NMXP_MSGBODY_CHANNELINFORESPONSE;
/*! \brief Channel info request body */
typedef struct {
int32_t key;
int32_t ignored;
} NMXP_MSGBODY_CHANNELINFOREQUEST;
/*! \brief Character separator for channel list */
#define sep_chan_list ','
/*! \brief Return type of data from a channel key */
#define getDataTypeFromKey(key) ((key >> 8) & 0xff)
/*! \brief Return channel number from a channel key */
#define getChannelNumberFromKey(key) ((key) & 0x000f)
/*! \brief Copy station code and channel code from name
*
* \param station_dot_channel string containing STA.CHAN
* \param[out] station_code Pointer to string for station code
* \param[out] channel_code Pointer to string for char code
*
* \warning Parametes can not be NULL!
*
* \retval 1 on success
* \retval 0 on error
*
*/
int nmxp_chan_cpy_sta_chan(const char *station_dot_channel, char *station_code, char *channel_code);
/*! \brief Match station_dot_channel against pattern, treating errors as no match.
*
* \param station_dot_channel STA.CHAN format
* \param pattern STA.?HZ or STA.H?Z or STA.HH? or STA.?H? or ....
*
* \retval 1 for match
* \retval 0 for no match
* \retval -1 on error for invalid pattern
* \retval -2 on error for invalid station_dot_channel
*
*/
int nmxp_chan_match(const char *station_dot_channel, char *pattern);
/*! \brief Looks up a channel key in the list using the name
*
* \param name Channel name.
* \param channelList Channel list.
*
* \return Key of the channel with name. -1 On error.
*
*/
int nmxp_chan_lookupKey(char* name, NMXP_CHAN_LIST *channelList);