diff options
Diffstat (limited to 'mbglib/common/mbgextio.h')
| -rw-r--r-- | mbglib/common/mbgextio.h | 2105 |
1 files changed, 2050 insertions, 55 deletions
diff --git a/mbglib/common/mbgextio.h b/mbglib/common/mbgextio.h index bbe6be9..adb0154 100644 --- a/mbglib/common/mbgextio.h +++ b/mbglib/common/mbgextio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgextio.h 1.8 2011/04/08 11:26:09 martin REL_M $ + * $Id: mbgextio.h 1.16.1.11 2015/07/22 16:02:08 martin TEST $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,68 @@ * * ----------------------------------------------------------------------- * $Log: mbgextio.h $ + * Revision 1.16.1.11 2015/07/22 16:02:08 martin + * Started to support variable USB endpoint numbers. + * Revision 1.16.1.10 2015/07/14 15:10:27 martin + * Updated function prototypes. + * Revision 1.16.1.9 2015/07/14 13:24:59 martin + * Updated function prototypes. + * Revision 1.16.1.8.1.10 2015/05/27 09:23:57 daniel + * Fixed USB_DIRECT_IO stuff + * Revision 1.16.1.8.1.9 2015/05/21 11:01:00 martin + * Updated function prototypes. + * Revision 1.16.1.8.1.8 2015/05/19 13:20:59 daniel + * Preliminary support for USB_DIRECT_IO + * Revision 1.16.1.8.1.6 2015/05/13 09:50:51 martin + * Added mbgextio_xmt_ack() and mbgextio_xmt_nack(). + * Revision 1.16.1.8.1.5 2015/04/15 15:36:19 martin + * Doxygen fixes. + * Revision 1.16.1.8.1.4 2015/03/03 10:14:50 martin + * Updated function prototypes. + * Revision 1.16.1.8.1.3 2014/11/04 15:09:37 martin + * More XBP stuff. + * Revision 1.16.1.8.1.2 2014/11/04 11:31:17 martin + * Revision 1.16.1.8.1.1 2014/10/30 16:14:07 martin + * Started to support XBP addressing. + * Revision 1.16.1.8 2014/10/30 16:03:09 martin + * Doxygen fixes. + * Revision 1.16.1.7 2014/10/30 14:47:06 martin + * Support FTDI devices. + * Updated USB support. + * Updated function prototypes. + * Revision 1.16.1.6 2013/11/28 15:51:48Z marvin + * Added mbgextio_get_ntp_peer_state_idx. + * Revision 1.16.1.5 2013/11/26 16:06:48Z marvin + * Added mbgextio_get_ntp_sys_state. + * Revision 1.16.1.4 2013/11/21 07:46:52Z marvin + * Added mbgextio_xmt_secu_settings. + * Revision 1.16.1.3 2013/11/12 12:12:05Z marvin + * Changed calls for NTP info and settings. + * Revision 1.16.1.2 2013/10/14 08:54:22Z marvin + * Added mbgextio_set_ntp_clnt_mode_cfg. + * Revision 1.16.1.1 2013/09/25 11:10:10Z marvin + * Added support for NTP and PTP. + * Revision 1.16 2013/09/10 08:56:35Z marvin + * Changed Doxygen comments. + * Revision 1.15 2013/09/05 15:11:40Z marvin + * Added support for LAN interface setup. + * Added support for PTP state. + * Added support for XMR. + * Added support for NTP info. + * Revision 1.14 2013/09/02 15:16:49Z marvin + * Added support for XMR (get multi ref info, set multi ref settings) + * Revision 1.13 2013/08/28 11:01:42Z marvin + * Added read and set tr_distance and gnss_mode. + * Revision 1.12 2013/04/11 14:18:47Z Gregoire + * new prototypes for sending havequick rx and tx settings to clock + * Revision 1.11 2013/02/06 15:44:57Z martin + * Updated function prototypes. + * Revision 1.10 2013/02/01 15:59:42 martin + * Updated function prototypes. + * Revision 1.9 2012/10/30 16:19:19 martin + * Support USB I/O. + * Started to migrate to opaque stuctures. + * Updated function prototypes. * Revision 1.8 2011/04/08 11:26:09 martin * New macros _ttm_time_set_unavail() and _ttm_time_is_avail(). * Revision 1.7 2009/10/02 14:21:08 martin @@ -38,7 +100,10 @@ /* Other headers to be included */ +#include <mbg_arch.h> #include <gpsserio.h> +#include <mbggeo.h> + #include <time.h> #ifdef _MBGEXTIO @@ -48,7 +113,6 @@ #define _ext extern #endif - /* Start of header body */ @@ -71,11 +135,34 @@ #endif // _USE_SERIAL_IO +#if !_USE_SERIAL_IO_FTDI + // just to avoid build errors if USB not supported + #define FT_STATUS int + #define FT_HANDLE int +#endif + + +#if !_USE_USB_IO + // just to avoid build errors if USB not supported + struct usb_device + { + int dummy; + }; + + typedef int MBG_USB_DEVICE; + +#endif + + #if !defined MBGEXTIO_READ_BUFFER_SIZE - #if _USE_SOCKET_IO + #if _USE_SOCKET_IO || _USE_USB_IO #define MBGEXTIO_READ_BUFFER_SIZE 1000 #else - #define MBGEXTIO_READ_BUFFER_SIZE 10 + #if defined _USE_USB_DIRECT_IO + #define MBGEXTIO_READ_BUFFER_SIZE 512 // Max. USB transfer buffer size + #else + #define MBGEXTIO_READ_BUFFER_SIZE 10 + #endif #endif #endif @@ -111,57 +198,1965 @@ extern "C" { /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - _MBG_API_ATTR int _MBG_API mbgextio_open_socket( MBG_MSG_CTL *pmctl, const char *host, const char *passwd ) ; - _MBG_API_ATTR int _MBG_API mbgextio_open_serial( MBG_MSG_CTL *pmctl, const char *dev, uint32_t baud_rate, const char *framing ) ; - _MBG_API_ATTR void _MBG_API mbgextio_close_connection( MBG_MSG_CTL *pmctl ) ; - _MBG_API_ATTR int _MBG_API mbgextio_force_connection( const char *dev ) ; - _MBG_API_ATTR void _MBG_API mbgextio_set_char_rcv_timeout( MBG_MSG_CTL *pmctl, ulong new_timeout ) ; - _MBG_API_ATTR ulong _MBG_API mbgextio_get_char_rcv_timeout( const MBG_MSG_CTL *pmctl ) ; - _MBG_API_ATTR void _MBG_API mbgextio_set_msg_rcv_timeout( MBG_MSG_CTL *pmctl, ulong new_timeout ) ; - _MBG_API_ATTR ulong _MBG_API mbgextio_get_msg_rcv_timeout( const MBG_MSG_CTL *pmctl ) ; - _MBG_API_ATTR int _MBG_API mbgextio_xmt_msg( MBG_MSG_CTL *pmctl, GPS_CMD cmd, const void *p, int n_bytes ) ; - _MBG_API_ATTR int _MBG_API mbgextio_rcv_msg( MBG_MSG_CTL *pmctl, GPS_CMD cmd ) ; - _MBG_API_ATTR int _MBG_API mbgextio_xmt_cmd( MBG_MSG_CTL *pmctl, GPS_CMD cmd ) ; - _MBG_API_ATTR int _MBG_API mbgextio_xmt_cmd_us( MBG_MSG_CTL *pmctl, GPS_CMD cmd, uint16_t us ) ; - _MBG_API_ATTR int _MBG_API mbgextio_req_data( MBG_MSG_CTL *pmctl, GPS_CMD cmd ) ; - _MBG_API_ATTR int _MBG_API mbgextio_req_data_idx( MBG_MSG_CTL *pmctl, GPS_CMD cmd, uint16_t idx ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_receiver_info( MBG_MSG_CTL *pmctl, RECEIVER_INFO *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_sw_rev( MBG_MSG_CTL *pmctl, SW_REV *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_bvar_stat( MBG_MSG_CTL *pmctl, BVAR_STAT *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_time( MBG_MSG_CTL *pmctl, TTM *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_time( MBG_MSG_CTL *pmctl, const TTM *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_pos_lla( MBG_MSG_CTL *pmctl, LLA lla ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_pos_lla( MBG_MSG_CTL *pmctl, const LLA lla ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_tzdl( MBG_MSG_CTL *pmctl, TZDL *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_tzdl( MBG_MSG_CTL *pmctl, const TZDL *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_port_parm( MBG_MSG_CTL *pmctl, PORT_PARM *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_port_parm( MBG_MSG_CTL *pmctl, const PORT_PARM *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_synth( MBG_MSG_CTL *pmctl, SYNTH *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_synth( MBG_MSG_CTL *pmctl, const SYNTH *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_ant_info( MBG_MSG_CTL *pmctl, ANT_INFO *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_ucap( MBG_MSG_CTL *pmctl, TTM *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_enable_flags( MBG_MSG_CTL *pmctl, ENABLE_FLAGS *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_enable_flags( MBG_MSG_CTL *pmctl, const ENABLE_FLAGS *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_stat_info( MBG_MSG_CTL *pmctl, STAT_INFO *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_ant_cable_len( MBG_MSG_CTL *pmctl, ANT_CABLE_LEN *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_ant_cable_len( MBG_MSG_CTL *pmctl, const ANT_CABLE_LEN *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_irig_tx_info( MBG_MSG_CTL *pmctl, IRIG_INFO *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_irig_tx_settings( MBG_MSG_CTL *pmctl, const IRIG_SETTINGS *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_irig_rx_info( MBG_MSG_CTL *pmctl, IRIG_INFO *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_irig_rx_settings( MBG_MSG_CTL *pmctl, const IRIG_SETTINGS *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_ref_offs( MBG_MSG_CTL *pmctl, MBG_REF_OFFS *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_ref_offs( MBG_MSG_CTL *pmctl, const MBG_REF_OFFS *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_debug_status( MBG_MSG_CTL *pmctl, MBG_DEBUG_STATUS *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_opt_info( MBG_MSG_CTL *pmctl, MBG_OPT_INFO *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_opt_settings( MBG_MSG_CTL *pmctl, const MBG_OPT_SETTINGS *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_str_type_info_idx( MBG_MSG_CTL *pmctl, STR_TYPE_INFO_IDX *p, uint16_t idx ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_port_info_idx( MBG_MSG_CTL *pmctl, PORT_INFO_IDX *p, uint16_t idx ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_port_settings_idx( MBG_MSG_CTL *pmctl, const PORT_SETTINGS *p, uint16_t idx ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_pout_info_idx( MBG_MSG_CTL *pmctl, POUT_INFO_IDX *p, uint16_t idx ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_pout_settings_idx( MBG_MSG_CTL *pmctl, const POUT_SETTINGS *p, uint16_t idx ) ; - _MBG_API_ATTR int _MBG_API mbgextio_clr_ucap_buff( MBG_MSG_CTL *pmctl ) ; - _MBG_API_ATTR int _MBG_API mbgextio_get_time_scale_info( MBG_MSG_CTL *pmctl, MBG_TIME_SCALE_INFO *p ) ; - _MBG_API_ATTR int _MBG_API mbgextio_set_time_scale_settings( MBG_MSG_CTL *pmctl, const MBG_TIME_SCALE_SETTINGS *p ) ; + /** + * @brief Send security settings for the socket connection + * + * If new_passwd is not a NULL pointer, the old_passwd + * will be overwritten by the new_passwd. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[in] old_passwd Pointer to the current LAN port password of the device + * @param[in] new_passwd Pointer to the new LAN port password for the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_open_socket + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_xmt_secu_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const char *old_passwd, const char *new_passwd ) ; + + /** + * @brief Open a binary communication channel via a LAN/socket connection + * + * @param[in] host DNS name or IP address of the target device + * @param[out] ppmctl Address of a pointer to a ::MBG_MSG_CTL control structure + * allocated and set up by this call. + * Pointer is set to NULL on error. + * @param[in] passwd Password string for the encrypted communication + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_open_serial + * @see ::mbgextio_open_serial_ftdi + * @see ::mbgextio_open_usb + * @see ::mbgextio_open_usb_direct_io + * @see ::mbgextio_close_connection + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_open_socket( const char *host, MBG_MSG_CTL **ppmctl, const char *passwd ) ; + + /** + * @brief Open a binary communication channel using direct serial I/O + * + * Commonly used serial parameters are 19200/8N1, see + * ::MBG_DEFAULT_BAUDRATE and ::MBG_DEFAULT_FRAMING. + * Some newer devices may also support ::MBG_DEFAULT_BAUDRATE_HS. + * + * @param[in] dev Name of the serial port to which the device is connected, + * depending on the naming conventions of the host system. + * @param[out] ppmctl Address of a pointer to a ::MBG_MSG_CTL control structure + * allocated and set up by this call. Set to NULL on error. + * @param[in] baud_rate Baud rate used for serial communication + * @param[in] framing Framing used for serial communication + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_force_conn_serial + * @see ::mbgextio_open_serial_ftdi + * @see ::mbgextio_force_conn_serial_ftdi + * @see ::mbgextio_open_socket + * @see ::mbgextio_open_usb + * @see ::mbgextio_open_usb_direct_io + * @see ::mbgextio_close_connection + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_open_serial( const char *dev, MBG_MSG_CTL **ppmctl, uint32_t baud_rate, const char *framing ) ; + + /** + * @brief Get the port handle of a serial FTDI device + * + * @param[in,out] pmctl Pointer to a valid message control structure + * + * @return the port handle retrieved from the message control structure + */ + _NO_MBG_API_ATTR FT_HANDLE _MBG_API mbgextio_get_serial_ftdi_port_handle( MBG_MSG_CTL *pmctl ) ; + + /** + * @brief Open a binary communication channel using serial FTDI D2xx port + * + * Commonly used serial parameters are 19200/8N1, see + * ::MBG_DEFAULT_BAUDRATE and ::MBG_DEFAULT_FRAMING. + * Some newer devices may also support ::MBG_DEFAULT_BAUDRATE_HS. + * + * @param[in] device_num device number from a list set up by FT_ListDevices() + * @param[out] ppmctl Address of a pointer to a ::MBG_MSG_CTL control structure + * allocated and set up by this call. Set to NULL on error. + * @param[in] baud_rate Baud rate used for serial communication + * @param[in] framing Framing used for serial communication + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_force_conn_serial_ftdi + * @see ::mbgextio_open_serial + * @see ::mbgextio_force_conn_serial + * @see ::mbgextio_open_socket + * @see ::mbgextio_open_usb + * @see ::mbgextio_open_usb_direct_io + * @see ::mbgextio_close_connection + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_open_serial_ftdi( int device_num, MBG_MSG_CTL **ppmctl, uint32_t baud_rate, const char *framing ) ; + + /** + * @brief Open a binary communication channel using direct USB I/O + * + * @param[in] usbdev The USB device to communicate with. + * @param[out] ppmctl Address of a pointer to a ::MBG_MSG_CTL control structure + * allocated and set up by this call. Set to NULL on error. + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_open_socket + * @see ::mbgextio_open_serial + * @see ::mbgextio_open_serial_ftdi + * @see ::mbgextio_close_connection + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_open_usb( const MBG_USB_DEVICE *usbdev, MBG_MSG_CTL **ppmctl ) ; + + /** + * @brief Open a binary communication channel using direct USB I/O + * + * Currently it is only supported by Linux systems since a file like + * USB device (e.g. "/dev/mbgims") is required and needs to support + * basic I/O operations like write, read, etc... + * + * @param[in] dev Path to file like USB device + * @param[in] flags Bitwise OR flags of access modes like W,RW,RO,etc. + * @param[out] ppmctl Address of a pointer to a ::MBG_MSG_CTL control structure + * allocated and set up by this call. Set to NULL on error. + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_open_socket + * @see ::mbgextio_open_serial + * @see ::mbgextio_open_serial_ftdi + * @see ::mbgextio_open_usb + * @see ::mbgextio_open_usb_direct_io + * @see ::mbgextio_close_connection + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_open_usb_direct_io( const char *dev, int flags, MBG_MSG_CTL **ppmctl ) ; + + /** + * @brief Close a binary communication channel and release resources + * + * Closes a binary communication channel which has been opened by one + * of the mbgextio_open_...() functions and releases the buffers which + * have been allocated when the channel was opened. + * + * The pointer to the message control structure passed by address is set + * to NULL after the channel has been closed and the resources have + * been released. + * + * @param[in,out] ppmctl Address of a pointer to a message control structure + * created when the communication channel was opened + * by one of the mbgextio_open_...() calls. + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_open_socket + * @see ::mbgextio_open_serial + * @see ::mbgextio_open_serial_ftdi + * @see ::mbgextio_open_usb + * @see ::mbgextio_open_usb_direct_io + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_close_connection( MBG_MSG_CTL **ppmctl ) ; + + /** + * @brief Try to force a serial connection to a device + * + * A device's serial port may have been configured to work by default + * in a way which is not appropriate for binary communication, e.g. using + * a low communication speed, or some framing like "7E2" which messes up + * binary data since the parity bit overrides a data bit. + * + * This function sends a special ASCII string to a device which lets the device + * temporarily switch to a specific baud rate and 8N1 framing which is usually + * used for binary communication, see ::MBG_DEFAULT_BAUDRATE, + * ::MBG_DEFAULT_BAUDRATE_HS, and ::MBG_DEFAULT_FRAMING. + * + * Since the current settings of the device's serial port are unknown this + * this command is sent in all common combinations of baud rates and + * framings. + * + * If the connected device supports this it should be possible to open + * the serial communication channel using the default parameters after + * this function has finished. + * + * @param[in] dev Name of the serial port to which the device is connected, + * depending on the naming conventions of the target system + * + * @return One of the negative @ref MBG_ERROR_CODES on error, + * else the determined baud rate. + * + * @see ::mbgextio_open_serial + * @see ::mbgextio_open_serial_ftdi + */ + _NO_MBG_API_ATTR long _MBG_API mbgextio_force_conn_serial( const char *dev ) ; + + /** + * @brief Try to force a serial connection to a device via the FTDI API + * + * A device's serial port may have been configured to work by default + * in a way which is not appropriate for binary communication, e.g. using + * a low communication speed, or some framing like "7E2" which messes up + * binary data since the parity bit overrides a data bit. + * + * This function sends a special ASCII string to a device which lets the device + * temporarily switch to a specific baud rate and 8N1 framing which is usually + * used for binary communication, see ::MBG_DEFAULT_BAUDRATE, + * ::MBG_DEFAULT_BAUDRATE_HS, and ::MBG_DEFAULT_FRAMING. + * + * Since the current settings of the device's serial port are unknown this + * this command is sent in all common combinations of baud rates and + * framings. + * + * If the connected device supports this it should be possible to open + * the serial communication channel using the default parameters after + * this function has finished. + * + * @param[in] device_num device number from a list set up by FT_ListDevices() + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_open_serial_ftdi + */ + _NO_MBG_API_ATTR long _MBG_API mbgextio_force_conn_serial_ftdi( int device_num ) ; + + /** + * @brief Retrieve address of the allocated receive buffer + * + * @param[in,out] pmctl Pointer to a valid message control structure + * + * @return Address of the allocated receive buffer + * + * @see ::mbgextio_get_rcv_buffer_size + * @see ::mbgextio_get_xmt_buffer_addr + * @see ::mbgextio_get_xmt_buffer_size + */ + _NO_MBG_API_ATTR MBG_MSG_BUFF * _MBG_API mbgextio_get_rcv_buffer_addr( MBG_MSG_CTL *pmctl ) ; + + /** + * @brief Retrieve size of the allocated receive buffer + * + * @param[in,out] pmctl Pointer to a valid message control structure + * + * @return Size of the allocated receive buffer + * + * @see ::mbgextio_get_rcv_buffer_addr + * @see ::mbgextio_get_xmt_buffer_addr + * @see ::mbgextio_get_xmt_buffer_size + */ + _NO_MBG_API_ATTR size_t _MBG_API mbgextio_get_rcv_buffer_size( MBG_MSG_CTL *pmctl ) ; + + /** + * @brief Retrieve address of the allocated transmit buffer + * + * @param[in,out] pmctl Pointer to a valid message control structure + * + * @return Address of the allocated transmit buffer + * + * @see ::mbgextio_get_rcv_buffer_addr + * @see ::mbgextio_get_rcv_buffer_size + * @see ::mbgextio_get_xmt_buffer_size + */ + _NO_MBG_API_ATTR MBG_MSG_BUFF * _MBG_API mbgextio_get_xmt_buffer_addr( MBG_MSG_CTL *pmctl ) ; + + /** + * @brief Retrieve size of the allocated transmit buffer + * + * @param[in,out] pmctl Pointer to a valid message control structure + * + * @return Size of the allocated transmit buffer + * + * @see ::mbgextio_get_rcv_buffer_addr + * @see ::mbgextio_get_rcv_buffer_size + * @see ::mbgextio_get_xmt_buffer_addr + */ + _NO_MBG_API_ATTR size_t _MBG_API mbgextio_get_xmt_buffer_size( MBG_MSG_CTL *pmctl ) ; + + /** + * @brief Set character receive timeout value + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] new_timeout New timeout value [ms] + * + * @see ::mbgextio_get_char_rcv_timeout + * @see ::mbgextio_set_msg_rcv_timeout + * @see ::mbgextio_get_msg_rcv_timeout + */ + _NO_MBG_API_ATTR void _MBG_API mbgextio_set_char_rcv_timeout( MBG_MSG_CTL *pmctl, ulong new_timeout ) ; + + /** + * @brief Get character receive timeout value + * + * @param[in,out] pmctl Pointer to a valid message control structure + * + * @return Current timeout value [ms] + * + * @see ::mbgextio_set_char_rcv_timeout + * @see ::mbgextio_set_msg_rcv_timeout + * @see ::mbgextio_get_msg_rcv_timeout + */ + _NO_MBG_API_ATTR ulong _MBG_API mbgextio_get_char_rcv_timeout( const MBG_MSG_CTL *pmctl ) ; + + /** + * @brief Set message receive timeout value + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] new_timeout New timeout value [ms] + * + * @see ::mbgextio_set_char_rcv_timeout + * @see ::mbgextio_get_char_rcv_timeout + * @see ::mbgextio_get_msg_rcv_timeout + */ + _NO_MBG_API_ATTR void _MBG_API mbgextio_set_msg_rcv_timeout( MBG_MSG_CTL *pmctl, ulong new_timeout ) ; + + /** + * @brief Get message receive timeout value + * + * @param[in,out] pmctl Pointer to a valid message control structure + * + * @return Current timeout value [ms] + * + * @see ::mbgextio_set_char_rcv_timeout + * @see ::mbgextio_get_char_rcv_timeout + * @see ::mbgextio_set_msg_rcv_timeout + */ + _NO_MBG_API_ATTR ulong _MBG_API mbgextio_get_msg_rcv_timeout( const MBG_MSG_CTL *pmctl ) ; + + /** + * @brief Generic reception of a binary message + * + * @note A certain message type to be waited for can be specified by + * passing one of the ::GPS_CMD_CODES. + * If the special cmd code ::GPS_WILDCARD is specified the function returns + * successfully after *any* type of binary message has been received. + * + * //##++ TODO: callback function to handle asynchronous spontaneous messages + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[in] cmd One of the command codes enumerated in ::GPS_CMD_CODES, or ::GPS_WILDCARD + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_rcv_msg + * @see ::mbgextio_xmt_msg //##++++ + * @see ::mbgextio_xmt_cmd + * @see ::mbgextio_req_data + * @see ::mbgextio_xmt_cmd_us + * @see ::mbgextio_req_data_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_rcv_msg( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, GPS_CMD cmd ) ; + + /** + * @brief Set up and send a generic binary message + * + * @note This function should preferably be used only as low level function + * called from within more specific functions used to send specific data. + * If this function is called directly with a buffer to be sent then the + * transmit mutex is acquired by this function. However, other (higher level) + * API functions which set up the transmit buffer directly have to acquire + * the transmit mutex by themselves before they set up the transmit buffer, + * and pass a NULL pointer to indicate the transmit buffer has already been + * set up. The correct number of bytes to send (n_bytes) has to be specified + * anyway, though. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[in] cmd One of the command codes enumerated in ::GPS_CMD_CODES + * @param[in] p Address of a data structure according to the specified cmd parameter, or NULL + * @param[in] n_bytes Size of the data structure addressed by parameter p + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_xmt_msg( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, GPS_CMD cmd, const void *p, uint16_t n_bytes ) ; + + /** + * @brief Transmit a command-only message without additional data. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[in] cmd One of the command codes enumerated in ::GPS_CMD_CODES + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_xmt_msg + * @see ::mbgextio_rcv_msg + * @see ::mbgextio_req_data + * @see ::mbgextio_xmt_cmd_us + * @see ::mbgextio_req_data_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_xmt_cmd( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, GPS_CMD cmd ) ; + + /** + * @brief Transmit a message without a single ushort (uint16_t) parameter + * + * The ushort parameter is often used to send an index value when requesting + * a certain element of an array of same data structures. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[in] cmd One of the command codes enumerated in ::GPS_CMD_CODES + * @param[in] us The ushort parameter for the command code + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_xmt_msg + * @see ::mbgextio_rcv_msg + * @see ::mbgextio_xmt_cmd + * @see ::mbgextio_req_data + * @see ::mbgextio_req_data_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_xmt_cmd_us( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, GPS_CMD cmd, uint16_t us ) ; + + /** + * @brief Transmit a message without a single ushort (16 bit) parameter + * + * The ushort parameter is often used to send an index value when requesting + * a specific element of an array of data structures. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[in] cmd One of the command codes enumerated in ::GPS_CMD_CODES + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_xmt_msg + * @see ::mbgextio_rcv_msg + * @see ::mbgextio_xmt_cmd + * @see ::mbgextio_xmt_cmd_us + * @see ::mbgextio_req_data_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_req_data( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, GPS_CMD cmd ) ; + + /** + * @brief Read a specific element of an array of data structures + * + * The type of data is implicitely associated with the cmd parameter. + * Usually the number of supported array elements has to be determined + * by some other means, e.g. from a field in the ::RECEIVER_INFO structure. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[in] cmd One of the command codes enumerated in ::GPS_CMD_CODES + * @param[in] idx The index of the array element to read + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_xmt_msg + * @see ::mbgextio_rcv_msg + * @see ::mbgextio_xmt_cmd + * @see ::mbgextio_req_data + * @see ::mbgextio_xmt_cmd_us + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_req_data_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, GPS_CMD cmd, uint16_t idx ) ; + + /** + * @brief Read a receiver info structure + * + * The ::RECEIVER_INFO should be read at first to identify the connected + * device and determine the basic features supported by the device. + * + * @note Some very old devices may not provide a ::RECEIVER_INFO, + * so ::mbgextio_setup_receiver_info should be called preferably + * to read the receiver info using this function, if supported, + * or set up a default structure for devices which don't provide + * a receiver info. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_setup_receiver_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_receiver_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, RECEIVER_INFO *p ) ; + + /** + * @brief Setup a receiver info structure + * + * The ::RECEIVER_INFO should be read at first to identify the connected + * device and determine the basic features supported by the device. + * + * @note Some very old devices may not provide a ::RECEIVER_INFO. + * This function tries to read the ::RECEIVER_INFO from the device, + * and sets up a default structure if the device doesn't support this. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_receiver_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_setup_receiver_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, RECEIVER_INFO *p ) ; + + /** + * @brief Read the software revision + * + * @deprecated This function is deprecated since the ::SW_REV structure + * is also a member of the ::RECEIVER_INFO. This call may be required, + * though, for very old devices which don't support the ::RECEIVER_INFO. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_setup_receiver_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_sw_rev( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, SW_REV *p ) ; + + /** + * @brief Read the status of buffered variables + * + * @note Only supported if ::GPS_MODEL_HAS_BVAR_STAT + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_bvar_stat( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, BVAR_STAT *p ) ; + + /** + * @brief Read the current time as ::TTM strucure + * + * @note This function is only supported by GPS receivers. + * + * The returned time is not very accurate since the response time + * transmission delay can't be determmined. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_time( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, TTM *p ) ; + + /** + * @brief Set the device's time by sending a ::TTM strucure + * + * @note The function is not supported by all devices. Time has to be + * passed as local time according to the device's ::TZDL settings. + * New time is only set with some tens of ms accuracy. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_time( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const TTM *p ) ; + + /** + * @brief Set the device's position by sending an ::LLA array + * + * @note This function is only supported by GPS receivers + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] lla Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_pos_lla( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const LLA lla ) ; + + /** + * @brief Read the current receiver position as ::LLA array + * + * @note This function is only supported by GPS receivers + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] lla Pointer to the data array to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_pos_lla( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, LLA lla ) ; + + /** + * @brief Read the current receiver position as ::XYZ array + * + * @note This function is only supported by GPS receivers + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] xyz Pointer to the data array to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_pos_xyz( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, XYZ xyz ) ; + + /** + * @brief Read the current receiver position as ::POS structure + * + * @note This function is only supported by GPS receivers + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p_pos Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_pos( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, POS *p_pos ) ; + + /** + * @brief Read the local time conversion parameters in ::TZDL format + * + * @note Some devices may not support ::TZDL settings + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_tzdl( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, TZDL *p ) ; + + /** + * @brief Set the local time conversion parameters in ::TZDL format + * + * @note Some devices may not support ::TZDL settings + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_tzdl( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const TZDL *p ) ; + + /** + * @brief Read serial port parameters in ::PORT_PARM format + * + * @deprecated This function is deprecated since the ::PORT_PARM structure + * supports only 2 serial ports, and does not not support configuration + * of a string type. The function ::mbgextio_get_serial_settings should + * be used instead. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_serial_settings + * @see ::mbgextio_save_serial_settings + * @see ::mbgextio_set_port_parm + * @see ::mbgextio_setup_receiver_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_port_parm( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, PORT_PARM *p ) ; + + /** + * @brief Send serial port parameters in ::PORT_PARM format + * + * @deprecated This function is deprecated since the ::PORT_PARM structure + * supports only 2 serial ports, and does not not support configuration + * of a string type. The function ::mbgextio_save_serial_settings should + * be used instead. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_serial_settings + * @see ::mbgextio_save_serial_settings + * @see ::mbgextio_get_port_parm + * @see ::mbgextio_setup_receiver_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_port_parm( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const PORT_PARM *p ) ; + + /** + * @brief Read the frequency synthesizer settings + * + * @note Some devices may not provide a frequency synthesizer + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_synth + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_synth( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, SYNTH *p ) ; + + /** + * @brief Write the frequency synthesizer settings + * + * @note Some devices may not provide a frequency synthesizer + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_synth + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_synth( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const SYNTH *p ) ; + + /** + * @brief Read the GPS antenna info structure + * + * @note This is only supported by GPS receivers. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ant_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, ANT_INFO *p ) ; + + /** + * @brief Read a user capture event in ::TTM format + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_clr_ucap_buff + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ucap( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, TTM *p ) ; + + /** + * @brief Read the enable flags controlling when output signals are enabled + * + * @note Some devices may not support ::ENABLE_FLAGS + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_enable_flags + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_enable_flags( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, ENABLE_FLAGS *p ) ; + + /** + * @brief Send the enable flags controlling when output signals are enabled + * + * @note Some devices may not support ::ENABLE_FLAGS + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_enable_flags + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_enable_flags( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const ENABLE_FLAGS *p ) ; + + /** + * @brief Read GPS status info + * + * @note This is only supported by GPS receivers + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_stat_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, STAT_INFO *p ) ; + + /** + * @brief Read the configured length of the antenna cable + * + * This is only supported by GPS/GNSS receivers, check ::GPS_MODEL_HAS_ANT_CABLE_LENGTH + * + * @note Some older devices may not reply to this request unless + * the application has registered itself as terminal application + * (GPS_AUTO_ON is not sufficient). + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_ant_cable_len + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ant_cable_len( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, ANT_CABLE_LEN *p ) ; + + /** + * @brief Send the GPS antenna cable length configuration + * + * This is only supported by GPS/GNSS receivers, check ::GPS_MODEL_HAS_ANT_CABLE_LENGTH + + * @note Different devices may accept different maximum values, so the + * written value should be re-read using ::mbgextio_get_ant_cable_len + * to check if the parameter has been accepted. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ant_cable_len + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_ant_cable_len( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const ANT_CABLE_LEN *p ) ; + + /** + * @brief Read configuration info and supported features of the device's IRIG output + * + * @note This is only supported if ::GPS_HAS_IRIG_TX is set in ::RECEIVER_INFO::features + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_irig_tx_settings + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_irig_tx_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, IRIG_INFO *p ) ; + + /** + * @brief Send new configuration settings for the device's IRIG output + * + * @note This is only supported if ::GPS_HAS_IRIG_TX is set in ::RECEIVER_INFO::features + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_irig_tx_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_irig_tx_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const IRIG_SETTINGS *p ) ; + + /** + * @brief Read configuration info and supported features for the device's IRIG input + * + * @note This is only supported if ::GPS_HAS_IRIG_RX is set in ::RECEIVER_INFO::features + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_irig_rx_settings + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_irig_rx_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, IRIG_INFO *p ) ; + + /** + * @brief Send new configuration settings for the device's IRIG input + * + * @note This is only supported if ::GPS_HAS_IRIG_RX is set in ::RECEIVER_INFO::features + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_irig_rx_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_irig_rx_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const IRIG_SETTINGS *p ) ; + + /** + * @brief Read current ref offset to %UTC configuration + * + * @note This is only supported if ::GPS_HAS_REF_OFFS is set in ::RECEIVER_INFO::features, + * usually with IRIG receivers + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_ref_offs + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ref_offs( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_REF_OFFS *p ) ; + + /** + * @brief Send new ref offset to %UTC settings + * + * @note This is only supported if ::GPS_HAS_REF_OFFS is set in ::RECEIVER_INFO::features, + * usually with IRIG receivers + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ref_offs + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_ref_offs( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const MBG_REF_OFFS *p ) ; + + /** + * @brief Read current debug status + * + * @note This is only supported if ::GPS_HAS_DEBUG_STATUS is set in ::RECEIVER_INFO::features, + * usually with IRIG receivers + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_debug_status( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_DEBUG_STATUS *p ) ; + + /** + * @brief Read current optional settings and supported options + * + * @note This is only supported if ::GPS_HAS_OPT_SETTINGS is set in ::RECEIVER_INFO::features + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_opt_settings + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_opt_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_OPT_INFO *p ) ; + + /** + * @brief Send new optional settings flags + * + * @note This is only supported if ::GPS_HAS_OPT_SETTINGS is set in ::RECEIVER_INFO::features + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_opt_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_opt_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const MBG_OPT_SETTINGS *p ) ; + + /** + * @brief Read information on a specific supported string format + * + * Retrieve a single entry from an array of supported string types. + * The number of supported string types is specified in ::RECEIVER_INFO::n_str_type. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the array element to be retrieved, 0..::RECEIVER_INFO::n_str_type - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_all_str_type_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_str_type_info_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, STR_TYPE_INFO_IDX *p, uint16_t idx ) ; + + /** + * @brief Read an array of all supported string types + * + * The number of supported string types is specified in ::RECEIVER_INFO::n_str_type. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] stii An array which can hold at least ::RECEIVER_INFO::n_str_type entries + * @param[in] p_ri Pointer to a valid ::RECEIVER_INFO structure + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_str_type_info_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_all_str_type_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ; + + /** + * @brief Read current settings and capabilities of a specific serial port + * + * The number of serial ports provided by the device is specified in ::RECEIVER_INFO::n_com_ports. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the array element to be retrieved, 0..::RECEIVER_INFO::n_com_ports - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_all_port_info + * @see ::mbgextio_set_port_settings_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_port_info_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, PORT_INFO_IDX *p, uint16_t idx ) ; + + /** + * @brief Read an array of current settings and capabilities of all serial ports + * + * The number of serial ports provided by the device is specified in ::RECEIVER_INFO::n_com_ports. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] pii An array which can hold at least ::RECEIVER_INFO::n_com_ports entries + * @param[in] p_ri Pointer to a valid ::RECEIVER_INFO structure + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_port_info_idx + * @see ::mbgextio_set_port_settings_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_all_port_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, PORT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ; + + /** + * @brief Send configuration settings for a specific serial port + * + * The number of serial ports provided by the device is specified in ::RECEIVER_INFO::n_com_ports. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * @param[in] idx Index of the serial port to be configured, 0..::RECEIVER_INFO::n_com_ports - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_port_info_idx + * @see ::mbgextio_get_all_port_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_port_settings_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const PORT_SETTINGS *p, uint16_t idx ) ; + + /** + * @brief Read current settings and capabilities of a specific programmable pulse output + * + * The number of supported pulse outputs is specified in ::RECEIVER_INFO::n_prg_out. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the array element to be retrieved, 0..::RECEIVER_INFO::n_prg_out - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_all_pout_info + * @see ::mbgextio_set_pout_settings_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_pout_info_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, POUT_INFO_IDX *p, uint16_t idx ) ; + + /** + * @brief Read an array of current settings and capabilities of all programmable pulse outputs + * + * The number of supported pulse outputs is specified in ::RECEIVER_INFO::n_prg_out. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] pii An array which can hold at least ::RECEIVER_INFO::n_prg_out entries + * @param[in] p_ri Pointer to a valid ::RECEIVER_INFO structure + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_pout_info_idx + * @see ::mbgextio_set_pout_settings_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_all_pout_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, POUT_INFO_IDX *pii, const RECEIVER_INFO *p_ri ) ; + + /** + * @brief Send configuration settings for a specific programmable pulse output + * + * The number of supported pulse outputs is specified in ::RECEIVER_INFO::n_prg_out. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * @param[in] idx Index of the pulse output to be configured, 0..RECEIVER_INFO::n_prg_out - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_pout_info_idx + * @see ::mbgextio_get_all_pout_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_pout_settings_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const POUT_SETTINGS *p, uint16_t idx ) ; + + /** + * @brief Clear the user capture event buffer on-board the device + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ucap + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_clr_ucap_buff( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr ) ; + + /** + * @brief Read time scale configuration parameters + * + * @note Some devices may not support a configurable time scale + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_time_scale_settings + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_time_scale_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_TIME_SCALE_INFO *p ) ; + + /** + * @brief Send new time scale configuration settings + * + * @note Some devices may not support a configurable time scale + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_time_scale_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_time_scale_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const MBG_TIME_SCALE_SETTINGS *p ) ; + + /** + * @brief Clear the on-board event log + * + * @note Some devices don't provide an on-board event log + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_num_evt_log_entries + * @see ::mbgextio_get_first_evt_log_entry + * @see ::mbgextio_get_next_evt_log_entry + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_clr_evt_log( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr ) ; + + /** + * @brief Read the current number of entries in the on-board event log + * + * @note Some devices don't provide an on-board event log + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_clr_evt_log + * @see ::mbgextio_get_first_evt_log_entry + * @see ::mbgextio_get_next_evt_log_entry + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_num_evt_log_entries( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_NUM_EVT_LOG_ENTRIES *p ) ; + + /** + * @brief Return the first entry from the on-board event log + * + * This resets an internal counter, so subsequent calls to + * ::mbgextio_get_next_evt_log_entry will retrieve the following entries. + * + * @note Some devices don't provide an on-board event log + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_clr_evt_log + * @see ::mbgextio_get_num_evt_log_entries + * @see ::mbgextio_get_next_evt_log_entry + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_first_evt_log_entry( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_EVT_LOG_ENTRY *p ) ; + + /** + * @brief Return the next entry from the on-board event log + * + * This increments an internal counter, so subsequent calls will + * return subsequent entries. ::mbgextio_get_first_evt_log_entry + * should be called first to reset the counter and retrieve the + * oldest log entry. + * + * @note Some devices don't provide an on-board event log + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_clr_evt_log + * @see ::mbgextio_get_num_evt_log_entries + * @see ::mbgextio_get_first_evt_log_entry + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_next_evt_log_entry( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_EVT_LOG_ENTRY *p ) ; + + /** + * @brief Read the current IMS state and supported IMS features + * + * @note This is only supported if ::GPS_HAS_IMS is set in ::RECEIVER_INFO::features + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ims_sensor_state_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ims_state( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_IMS_STATE *p ) ; + + /** + * @brief Read sensor values from a specified sensor on the device + * + * Info on supported sensors can be retrieved using ::mbgextio_get_ims_state. + * Valid range for the sensor index is [0..::MBG_IMS_STATE::num_sensors - 1]. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx The index of the array element to read + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ims_state + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ims_sensor_state_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_IMS_SENSOR_STATE_IDX *p, uint16_t idx ) ; + + /** + * @brief Set the XMR holdover interval + * + * @todo In which case is this supported? + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_holdover_interval_counter + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_holdover_interval( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const XMR_HOLDOVER_INTV *p ) ; + + /** + * @brief Read the XMR holdover interval counter + * + * @todo In which case is this supported? + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_holdover_interval + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_holdover_interval_counter( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, XMR_HOLDOVER_INTV *p ) ; + + /** + * @brief Read the local time conversion configuration in ::TZCODE format + * + * @note Some devices may not support ::TZCODE configuration + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_tzcode + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_tzcode( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, TZCODE *p ) ; + + /** + * @brief Set the local time conversion configuration in ::TZCODE format + * + * @note Some devices may not support ::TZCODE configuration + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_tzcode + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_tzcode( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const TZCODE *p ) ; + + /** + * @brief Send new configuration settings for the device's HAVEQUICK output + * + * @note This is only supported if ::GPS_HAS_HAVEQUICK is set in ::RECEIVER_INFO::features + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_hq_tx_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, HAVEQUICK_SETTINGS *p ) ; + + /** + * @brief Send new configuration settings for the device's HAVEQUICK input + * + * @note This is only supported if ::MULTI_REF_HAVEQUICK is > 0 in ::XMULTI_REF_INSTANCES::n_inst //##+++++++++++++++++++++++ ??? + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_hq_rx_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, HAVEQUICK_SETTINGS *p ) ; + + /** + * @brief Read the distance from transmitter ::TR_DISTANCE format + * + * @note Some devices may not support ::TR_DISTANCE configuration + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_tr_distance + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_tr_distance( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, TR_DISTANCE *p ) ; + + /** + * @brief Set the transmitter distance (km) in ::TR_DISTANCE format + * + * @note Some devices may not support ::TR_DISTANCE configuration + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_tr_distance + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_tr_distance( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const TR_DISTANCE *p ) ; + + /** + * @brief Read current GNSS mode settings and supported features + * + * @note Some devices may not support GNSS configuration + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_gnss_mode_settings + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_gnss_mode_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_GNSS_MODE_INFO *p ) ; + + /** + * @brief Write GNSS mode settings + * + * @note Some devices may not support GNSS configuration + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[in] p Pointer to a ::MBG_GNSS_MODE_SETTINGS structure to be sent + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_gnss_mode_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_gnss_mode_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const MBG_GNSS_MODE_SETTINGS *p ) ; + + /** + * @brief Read an array of all supported string types //##+++++++++++++++++++++++++++++++++++++++++++++++ TODO + * + * The number of supported string types is specified in ::RECEIVER_INFO::n_str_type. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] stii An array which can hold at least ::RECEIVER_INFO::n_str_type entries + * @param[in] p_ri Pointer to a valid ::RECEIVER_INFO structure + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_str_type_info_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_all_gnss_sat_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ; + + /** + * @brief Fill up a GNSS info structure //##+++++++++++++++++++++++++++++++++++++++++++++++ TODO + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[out] p_si Pointer to a ::STAT_INFO the data structure to return the received data + * @param[out] p_gmi Index of the NTP peer state to be configured, 0..::NTP_CLNT_MODE_INFO::n_supp_peers - 1 + * @param[out] p_gsii Blah ... //##++++++++++ TODO + * @param[in] p_ri Pointer to a valid ::RECEIVER_INFO structure + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ntp_sys_state + * @see ::mbgextio_get_ntp_peer_settings_idx + * @see ::mbgextio_get_ntp_clnt_mode_info + */ + int mbgextio_chk_get_gnss_info( MBG_MSG_CTL *pmctl, STAT_INFO *p_si, MBG_GNSS_MODE_INFO *p_gmi, GNSS_SAT_INFO_IDX *p_gsii, const RECEIVER_INFO *p_ri ) ; + + /** + * @brief Read the supported XMR features in ::XMULTI_REF_INFO_IDX format + * + * Only if ::GPS_HAS_XMULTI_REF is set in ::RECEIVER_INFO::features. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_xmr_info_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_xmr_info_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, XMULTI_REF_INFO_IDX *p ) ; + + /** + * @brief Read the supported XMR features ::XMULTI_REF_STATUS_IDX format + * + * @note Only for devices which supports Multi references + * @note GPS_HAS_XMULTI_REF feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_xmr_info_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_xmr_status_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, XMULTI_REF_STATUS_IDX *p ) ; + + /** + * @brief Save the supported XMR features ::XMULTI_REF_INFO_IDX format + * + * @note Some devices may not support Multi Refernce Sources + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_xmr_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const XMULTI_REF_SETTINGS_IDX *p ) ; + + /** + * @brief Read the lan interface configuration ::LAN_IF_INFO format + * + * @note ptp or xmr with ntp feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_lan_if_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, LAN_IF_INFO *p ) ; + + /** + * @brief Read the lan ipv4 configuration state ::IP4_SETTINGS format + * + * @note ptp or xmr with ntp feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ip4_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, IP4_SETTINGS *p ) ; + + /** + * @brief Save the current ipv4 settings ::IP4_SETTINGS format + * + * @note ptp or xmr with ntp feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_ip4_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const IP4_SETTINGS *p ) ; + + /** + * @brief Read the current lan ipv4 state ::IP4_SETTINGS format + * + * @note ptp or xmr with ntp feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ip4_state( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, IP4_SETTINGS *p ) ; + + /** + * @brief Read the current state of PTP device ::PTP_STATE format + * + * @note ptp feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ptp_state( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, PTP_STATE *p ) ; + + /** + * @brief Read the ptp configuration ::PTP_CFG_INFO format + * + * @note ptp feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ptp_cfg_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, PTP_CFG_INFO *p ) ; + + /** + * @brief Read the ptp configuration ::PTP_UC_MASTER_CFG_LIMITS format + * + * @note ptp feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ptp_uc_master_cfg_limits( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, PTP_UC_MASTER_CFG_LIMITS *p ) ; + + /** + * @brief Read the ptp configuration ::ALL_PTP_UC_MASTER_INFO_IDX format + * + * @note ptp feature must set and read number of ptp unicast masters before. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] ptp_uc_master_info_idx Pointer to an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up + * @param[in] ptp_uc_master_cfg_limits Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure read before + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see //##+++++++++++++ TODO + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_all_ptp_uc_master_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, PTP_UC_MASTER_INFO_IDX *ptp_uc_master_info_idx, const PTP_UC_MASTER_CFG_LIMITS *ptp_uc_master_cfg_limits ) ; + + /** + * @brief Send configuration settings for PTP + * + * @note This is only supported by PTP devices + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ptp_cfg_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_ptp_cfg_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const PTP_CFG_SETTINGS *p ) ; + + /** + * @brief Read the ntp global information ::NTP_GLB_INFO format + * + * @note ntp feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ntp_clnt_mode_info + * @see ::mbgextio_get_ntp_peer_settings_idx + * @see ::mbgextio_set_ntp_peer_settings_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ntp_glb_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, NTP_GLB_INFO *p ) ; + + /** + * @brief Send the NTP global configuration + * + * @note This is only supported by NTP devices + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ant_cable_len + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_ntp_glb_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const NTP_GLB_SETTINGS *p ) ; + + /** + * @brief Read the ntp global information ::NTP_CLNT_MODE_INFO format + * + * @note ntp feature must set + * @note ntp client mode must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ntp_glb_info + * @see ::mbgextio_set_ntp_clnt_mode_cfg + * @see ::mbgextio_get_ntp_peer_settings_idx + * @see ::mbgextio_set_ntp_peer_settings_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ntp_clnt_mode_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, NTP_CLNT_MODE_INFO *p ) ; + + /** + * @brief Send the NTP client mode configuration + * + * @note This is only supported by NTP devices + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ntp_glb_info + * @see ::mbgextio_get_ntp_clnt_mode_info + * @see ::mbgextio_get_ntp_peer_settings_idx + * @see ::mbgextio_set_ntp_peer_settings_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_ntp_clnt_mode_cfg( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const NTP_CLNT_MODE_SETTINGS *p ) ; + + /** + * @brief Read the ntp peer settings of current idx ::NTP_PEER_SETTINGS format + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the NTP peer settings to be configured, 0 ... NTP_CLNT_MODE_INFO::n_supp_peers - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ntp_glb_info + * @see ::mbgextio_set_ntp_peer_settings_idx + * @see ::mbgextio_get_ntp_clnt_mode_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ntp_peer_settings_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, NTP_PEER_SETTINGS_IDX *p, uint16_t idx ) ; + + /** + * @brief Send configuration settings for a specific NTP peer + * + * The number of supported NTP peers is specified in ::NTP_CLNT_MODE_INFO::n_supp_peers -1. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * @param[in] idx Index of the NTP peer to be configured, 0 ... NTP_CLNT_MODE_INFO::n_supp_peers - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ntp_glb_info + * @see ::mbgextio_get_ntp_peer_settings_idx + * @see ::mbgextio_get_ntp_clnt_mode_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_ntp_peer_settings_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const NTP_PEER_SETTINGS *p, uint16_t idx ) ; + + /** + * @brief Read the current system state of ntp device ::NTP_SYS_STATE format + * + * @note ntp feature must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_ntp_clnt_mode_cfg + * @see ::mbgextio_get_ntp_glb_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ntp_sys_state( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, NTP_SYS_STATE *p ) ; + + /** + * @brief Read the NTP peer state of current idx ::NTP_PEER_STATE format + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the NTP peer state to be configured, 0 ... NTP_CLNT_MODE_INFO::n_supp_peers - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_ntp_sys_state + * @see ::mbgextio_get_ntp_peer_settings_idx + * @see ::mbgextio_get_ntp_clnt_mode_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ntp_peer_state_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, NTP_PEER_STATE_IDX *p, uint16_t idx ) ; + + /** + * @brief Read the network global config information ::MBG_NET_GLB_CFG_INFO format + * + * @note GPS_HAS_NET_CFG must set + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_net_glb_cfg_settings + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_net_glb_cfg_info( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_NET_GLB_CFG_INFO *p ) ; + + /** + * @brief Set the device's global network configuration settings + * + * @note The function is not supported by all devices. //##++++++++++++ + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_net_glb_cfg_info + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_net_glb_cfg_settings( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const MBG_NET_GLB_CFG_SETTINGS *p ) ; + + /** + * @brief Read the network dns server ::MBG_IP_ADDR_IDX format + * + * The number of DNS server provided by the device is specified in ::MBG_NET_GLB_CFG_INFO::num_dns_srvr + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the array element to be retrieved, 0..::MBG_NET_GLB_CFG_INFO::num_dns_srvr - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_net_dns_srvr_idx + * @see ::mbgextio_get_net_stat_dns_srvr_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_net_dns_srvr_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_IP_ADDR_IDX *p, uint16_t idx ) ; + + /** + * @brief Send the network DNS server address in ::MBG_IP_ADDR format + * + * The number of DNS search domains supported by the device + * is specified in ::MBG_NET_GLB_CFG_INFO::num_dns_srch_dom + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * @param[in] idx Index of the serial port to be configured, 0..::MBG_NET_GLB_CFG_INFO::num_dns_srvr - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_net_dns_srvr_idx + * @see ::mbgextio_get_net_stat_dns_srvr_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_net_dns_srvr_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const MBG_IP_ADDR *p, uint16_t idx ) ; + + /** + * @brief Read the network DNS search domain in ::MBG_NET_NAME_IDX format + * + * The number of DNS search domains supported by the device + * is specified in ::MBG_NET_GLB_CFG_INFO::num_dns_srch_dom + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the array element to be retrieved, 0..::MBG_NET_GLB_CFG_INFO::num_dns_srch_dom - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_net_dns_srch_dom_idx + * @see ::mbgextio_get_net_stat_dns_srch_dom_stat_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_net_dns_srch_dom_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_NET_NAME_IDX *p, uint16_t idx ) ; + + /** + * @brief Send the network DNS search domain in ::MBG_NET_NAME format + * + * The number of DNS search domains supported by the device + * is specified in ::MBG_NET_GLB_CFG_INFO::num_dns_srch_dom + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * @param[in] idx Index of the serial port to be configured, 0..::MBG_NET_GLB_CFG_INFO::num_dns_srch_dom - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_net_dns_srch_dom_idx + * @see ::mbgextio_get_net_stat_dns_srch_dom_stat_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_net_dns_srch_dom_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, const MBG_NET_NAME *p, uint16_t idx ) ; + + /** + * @brief Read the current network DNS server in ::MBG_IP_ADDR_IDX format + * + * The number of DNS servers supported by the device + * is specified in ::MBG_NET_GLB_CFG_INFO::num_dns_srvr + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the array element to be retrieved, 0..::MBG_NET_GLB_CFG_INFO::num_dns_srvr - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_net_dns_srvr_idx + * @see ::mbgextio_set_net_dns_srvr_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_net_stat_dns_srvr_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_IP_ADDR_IDX *p, uint16_t idx ) ; + + /** + * @brief Read the current network DNS search domain in ::MBG_NET_NAME_IDX format + * + * The number of DNS search domains supported by the device + * is specified in ::MBG_NET_GLB_CFG_INFO::num_dns_srch_dom + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the array element to be retrieved, 0..::MBG_NET_GLB_CFG_INFO::num_dns_srch_dom - 1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_net_dns_srch_dom_idx + * @see ::mbgextio_get_net_dns_srch_dom_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_net_stat_dns_srch_dom_stat_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, MBG_NET_NAME_IDX *p, uint16_t idx ) ; + + /** + * @brief Read the ::XBP_LIMITS to check which XBP features are supported + * + * @note Only supported if ::GPS_HAS_XBP is set in ::RECEIVER_INFO::features + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_xbp_node_limits + * @see ::mbgextio_get_xbp_node_info_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_xbp_limits( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, XBP_LIMITS *p ) ; + + /** + * @brief Read the ::XBP_NODE_LIMITS to check how many ports are provided + * + * @note Only supported if ::XBP_FEAT_MASK_NODES is set in ::XBP_LIMITS::features. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_xbp_limits + * @see ::mbgextio_get_xbp_node_info_idx + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_xbp_node_limits( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, XBP_NODE_LIMITS *p ) ; + + /** + * @brief Read the ::XBP_NODE_INFO for a specific node in ::XBP_NODE_INFO_IDX format + * + * The supported number of nodes is provided by ::XBP_NODE_LIMITS::node_count. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * @param[in] idx Index of the array element to be retrieved, 0..::XBP_NODE_LIMITS::node_count-1 + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_xbp_limits + * @see ::mbgextio_get_xbp_node_limits + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_xbp_node_info_idx( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, XBP_NODE_INFO_IDX *p, uint16_t idx ) ; + + /** + * @brief Read the ::XBP_NODE_INFO for a specific node in ::XBP_NODE_INFO_IDX format + * //##+++++++++++++++++++++++++ + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_setup_xbp_node_list( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr ) ; + + /** + * @brief Read a ::UTC parameter structure from a device. + * + * The ::UTC parameter structure contains the current UTC/GPS time offset + * as well as information on an eventually upcoming leap second. + * + * @note Only supported by GPS/GNSS and some PZF receivers //##+++++++ TODO Associated feature flag? + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to return the received data + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_set_utc_param + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_get_utc_param( MBG_MSG_CTL *pmctl, XBP_ADDR *p_addr, UTC *p ) ; + + /** + * @brief Write a ::UTC parameter structure to a device. + * + * The ::UTC parameter structure contains the current UTC/GPS time offset + * as well as information on an eventually upcoming leap second. + * + * @note Only supported by GPS/GNSS and some PZF receivers //##+++++++ TODO Associated feature flag? + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to an XBP address specifier, or NULL + * @param[out] p Pointer to the data structure to be sent to the device + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_get_utc_param + */ + _NO_MBG_API_ATTR int _MBG_API mbgextio_set_utc_param( MBG_MSG_CTL *pmctl, XBP_ADDR *p_addr, const UTC *p ) ; + /* ----- function prototypes end ----- */ |