src/fap.h File Reference

Declaration of libfap's public interface. More...

#include <time.h>

Include dependency graph for fap.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	fap_wx_report_t
	Weather report type. More...
struct	fap_telemetry_t
	Telemetry report type. More...
struct	fap_packet_t
	APRS packet type. More...
Enumerations
enum	fap_error_code_t {   fapPACKET_NO, fapPACKET_SHORT, fapPACKET_NOBODY, fapSRCCALL_NOAX25,   fapSRCCALL_BADCHARS, fapDSTPATH_TOOMANY, fapDSTCALL_NONE, fapDSTCALL_NOAX25,   fapDIGICALL_NOAX25, fapDIGICALL_BADCHARS, fapTIMESTAMP_INV_LOC, fapTIMESTAMP_INV_OBJ,   fapTIMESTAMP_INV_STA, fapTIMESTAMP_INV_GPGGA, fapTIMESTAMP_INV_GPGLL, fapPACKET_INVALID,   fapNMEA_INV_CVAL, fapNMEA_LARGE_EW, fapNMEA_LARGE_NS, fapNMEA_INV_SIGN,   fapNMEA_INV_CKSUM, fapGPRMC_FEWFIELDS, fapGPRMC_NOFIX, fapGPRMC_INV_TIME,   fapGPRMC_INV_DATE, fapGPRMC_DATE_OUT, fapGPGGA_FEWFIELDS, fapGPGGA_NOFIX,   fapGPGLL_FEWFIELDS, fapGPGLL_NOFIX, fapNMEA_UNSUPP, fapOBJ_SHORT,   fapOBJ_INV, fapOBJ_DEC_ERR, fapITEM_SHORT, fapITEM_INV,   fapITEM_DEC_ERR, fapLOC_SHORT, fapLOC_INV, fapLOC_LARGE,   fapLOC_AMB_INV, fapMICE_SHORT, fapMICE_INV, fapMICE_INV_INFO,   fapMICE_AMB_LARGE, fapMICE_AMB_INV, fapMICE_AMB_ODD, fapCOMP_INV,   fapCOMP_SHORT, fapMSG_INV, fapWX_UNSUPP, fapUSER_UNSUPP,   fapDX_INV_SRC, fapDX_INF_FREQ, fapDX_NO_DX, fapTLM_INV,   fapTLM_LARGE, fapTLM_UNSUPP, fapEXP_UNSUPP, fapSYM_INV_TABLE,   fapNOT_IMPLEMENTED, fapNMEA_NOFIELDS, fapNO_APRS }
	Packet error code type.
enum	fap_packet_type_t {   fapLOCATION, fapOBJECT, fapITEM, fapMICE,   fapNMEA, fapWX, fapMESSAGE, fapCAPABILITIES,   fapSTATUS, fapTELEMETRY, fapTELEMETRY_MESSAGE, fapDX_SPOT,   fapEXPERIMENTAL }
	Packet type type.
enum	fap_pos_format_t { fapPOS_COMPRESSED, fapPOS_UNCOMPRESSED, fapPOS_MICE, fapPOS_NMEA }
	Position format type.
Functions
fap_packet_t *	fap_parseaprs (char const *input, unsigned int const input_len, short const is_ax25)
	The parser.
void	fap_explain_error (fap_error_code_t const error, char *buffer)
	Return human-readable error message for given error code.
void	fap_mice_mbits_to_message (char const *bits, char *buffer)
	Convert mic-e message bits (three numbers 0-2) to a textual message.
double	fap_distance (double lon0, double lat0, double lon1, double lat1)
	Calculate distance between given locations.
double	fap_direction (double lon0, double lat0, double lon1, double lat1)
	Calculate direction from first to second location.
int	fap_count_digihops (fap_packet_t const *packet)
	Count amount of digihops the packet has gone through.
char *	fap_check_ax25_call (char const *input, short const add_ssid0)
	Check if the callsign is a valid AX.25 callsign.
int	fap_kiss_to_tnc2 (char const *kissframe, unsigned int kissframe_len, char *tnc2frame, unsigned int *tnc2frame_len, unsigned int *tnc_id)
	Convert a KISS-frame into a TNC-2 compatible UI-frame.
int	fap_tnc2_to_kiss (char const *tnc2frame, unsigned int tnc2frame_len, unsigned int const tnc_id, char *kissframe, unsigned int *kissframe_len)
	Convert a TNC-2 compatible UI-frame into a KISS data frame.
int	fap_ax25_to_tnc2 (char const *ax25frame, unsigned int ax25frame_len, char *tnc2frame, unsigned int *tnc2frame_len)
	Convert raw AX.25 frame into TNC-2 compatible UI-frame.
int	fap_tnc2_to_ax25 (char const *tnc2frame, unsigned int tnc2frame_len, char *ax25frame, unsigned int *ax25frame_len)
	Convert TNC-2 compatible UI-frame into raw AX.25-frame.
void	fap_free (fap_packet_t *packet)
	Custom free() for fap_packet_t*.
void	fap_init ()
	Library initialization.
void	fap_cleanup ()
	Library cleanup.

---

Detailed Description

Declaration of libfap's public interface.

This file declares data types used to represent a single APRS packet. Functions include the parser, some utility functions and library initialization stuff.

Note: it is very important to call fap_init() before calling any other function. Also note that fap_cleanup() should be called when shutting down, or memory leaks will occur.

Author:

Tapio Aaltonen

Definition in file fap.h.

---

Function Documentation

fap_packet_t* fap_parseaprs	(	char const *	input,
		unsigned int const	input_len,
		short const	is_ax25
	)

The parser.

Resulting packet object will be filled with as much data as possible based on the packet given as parameter. Unfilled fields are set to NULL.

When parsing in AX.25 mode, source callsign and path elements are checked to be strictly compatible with AX.25 specs so that they can be sent into AX.25 network. Destination callsign is always checked this way.

The parser should handle null bytes, newline chars and other badness sometimes seen in packets without crashing as long as input_len is given correctly.

Parameters:

	input	TNC-2 mode APRS packet string.
	input_len	Amount of bytes in input.
	is_ax25	If 1, packet is parsed as AX.25 network packet. If 0, packet is parsed as APRS-IS packet.

Returns:

A packet is always returned, no matter how the parsing went. Use error_code to check how it did. If library is not initialized, returns NULL.

Definition at line 140 of file fap.c.

void fap_explain_error	(	fap_error_code_t const	error,
		char *	buffer
	)

Return human-readable error message for given error code.

Parameters:

	error	Error code from fap_packet_t.
	buffer	Pre-allocated space for the message. Must be at least 60 bytes long.

Definition at line 510 of file fap.c.

void fap_mice_mbits_to_message	(	char const *	bits,
		char *	buffer
	)

Convert mic-e message bits (three numbers 0-2) to a textual message.

Parameters:

	bits	Bits as returned by fap_parseaprs().
	buffer	Pre-allocated space for the message. Must be at least 20 bytes long.

Definition at line 740 of file fap.c.

double fap_distance	(	double	lon0,
		double	lat0,
		double	lon1,
		double	lat1
	)

Calculate distance between given locations.

Returns the distance in kilometers between two locations given in decimal degrees. Arguments are given in order as lon0, lat0, lon1, lat1, east and north positive. The calculation uses the great circle distance, it is not too exact, but good enough for us.

Definition at line 769 of file fap.c.

double fap_direction	(	double	lon0,
		double	lat0,
		double	lon1,
		double	lat1
	)

Calculate direction from first to second location.

Returns the initial great circle direction in degrees from lat0/lon0 to lat1/lon1. Locations are input in decimal degrees, north and east positive.

Definition at line 789 of file fap.c.

int fap_count_digihops

(

fap_packet_t const *

packet

)

Count amount of digihops the packet has gone through.

The number returned is just an educated guess, not absolute truth.

Returns:

Number of digipeated hops or -1 in case of error.

Definition at line 813 of file fap.c.

char* fap_check_ax25_call	(	char const *	input,
		short const	add_ssid0
	)

Check if the callsign is a valid AX.25 callsign.

Parameters:

	input	Callsign to be checked. If SSID is 0, the "-0" suffix can be omitted.
	add_ssid0	If 1, a missing SSID 0 (in practice "-0") is appended to the returned callsign. If 0, valid callsign is returned as is.

Returns:

Given input if it was valid. NULL if the input was not a valid AX.25 address or library is not initialized.

Please note that it's very common to use invalid callsigns on the APRS-IS.

Definition at line 894 of file fap.c.

int fap_kiss_to_tnc2	(	char const *	kissframe,
		unsigned int	kissframe_len,
		char *	tnc2frame,
		unsigned int *	tnc2frame_len,
		unsigned int *	tnc_id
	)

Convert a KISS-frame into a TNC-2 compatible UI-frame.

Non-UI and non-pid-F0 frames are dropped. The KISS-frame to be decoded may or may not have a FEND (0xC0) character at beginning. If there's a FEND in the frame before or at the end, the frame is cutted just before the FEND. Byte unstuffing must not be done before calling this function.

Parameters:

	kissframe	KISS-frame.
	kissframe_len	Amount of bytes in kissframe. Must be less than 512.
	tnc2frame	Result of conversion is stored here. In case of error an error message may be found here.
	tnc2frame_len	Amount of bytes available in tnc2frame is read from here. Amount of bytes written to tnc2frame is written to here upon return.
	tnc_id	TNC ID from the kissframe, usually zero.

Returns:

1 in case of success, 0 when error occured.

Definition at line 964 of file fap.c.

int fap_tnc2_to_kiss	(	char const *	tnc2frame,
		unsigned int	tnc2frame_len,
		unsigned int const	tnc_id,
		char *	kissframe,
		unsigned int *	kissframe_len
	)

Convert a TNC-2 compatible UI-frame into a KISS data frame.

The frame will be complete, i.e. it has byte stuffing done and FEND (0xC0) characters on both ends.

Parameters:

	tnc2frame	TNC-2 frame.
	tnc2frame_len	Amount of bytes in tnc2frame.
	tnc_id	TNC ID to use in KISS frame. When is doubt, use zero.
	kissframe	Where to store the KISS-frame. Be sure to allocate enough space.
	kissframe_len	Amount of bytes stored into kissframe during successfull conversion.

Returns:

1 in case of success, 0 when error occured.

Definition at line 1251 of file fap.c.

int fap_ax25_to_tnc2	(	char const *	ax25frame,
		unsigned int	ax25frame_len,
		char *	tnc2frame,
		unsigned int *	tnc2frame_len
	)

Convert raw AX.25 frame into TNC-2 compatible UI-frame.

Params and return value work just like similar ones in fap_kiss_to_tnc2().

Definition at line 1063 of file fap.c.

int fap_tnc2_to_ax25	(	char const *	tnc2frame,
		unsigned int	tnc2frame_len,
		char *	ax25frame,
		unsigned int *	ax25frame_len
	)

Convert TNC-2 compatible UI-frame into raw AX.25-frame.

Params and return value work just like similar ones in fap_tnc2_to_kiss().

Definition at line 1313 of file fap.c.

void fap_free

(

fap_packet_t *

packet

)

Custom free() for fap_packet_t*.

Use this in place of normal free() when disposing a packet. Will free() all non-NULL fields for you.

Definition at line 1735 of file fap.c.

void fap_init

(

)

Library initialization.

This must be called once and before anything else when starting to use libfap in your program.

Definition at line 1570 of file fap.c.

void fap_cleanup

(

)

Library cleanup.

This must be called once when closing your app. Make sure that no fap calls are issued after this.

Definition at line 1653 of file fap.c.