utServerLocation.c File Reference

This system handles parsing a server location list, storing various locations, and selecting one for the cellular module to use. More...

#include "uTrack.h"
#include "utStrings.h"
#include "utServerLocation.h"
#include <stdlib.h>
#include <ctype.h>

Data Structures
union	UT_uServeAddress
struct	UT_uServeLocator

Macros
#define	USER_USERVE_LOCATIONS   3
#define	MAX_USERVE_LOCATIONS   USER_USERVE_LOCATIONS + 1
#define	DEFAULT_INDEX   0
#define	REQ_ITEMS_PER_LINE   2
#define	MIN_USEFUL_LINE_LEN   15 - 1

Enumerations
enum	UT_ITEM_TYPE { IP = 0 , DNS , PORT , UT_ITEM_TYPE_MAX }

Functions
bool	utServerLocation_HandleLine (const char *line, u8 lineLength)
bool	utServerLocation_HasIP (void)
const char *	utServerLocation_GetIP (void)
void	utServerLocation_SetIP (const char *inf, u8 length)
bool	utServerLocation_HasDNS (void)
const char *	utServerLocation_GetDNS (void)
void	utServerLocation_Fallback (void)
void	utServerLocation_Clear (void)
int	utServerLocation_GetPort (void)
void	utServerLocation_SetDefaultAllowed (bool allowed)
bool	utServerLocation_GetDefaultAllowed (void)
const char *	utServerLocation_GetOverrideAddress (void)
int	utServerLocation_GetOverridePort (void)
void	utServerLocation_SetOverrideLocation (const char *address, bool isIP, u16 port)
bool	utServerLocation_IsOverridden (void)
void	utServerLocation_ClearOverride (void)

Detailed Description

This system handles parsing a server location list, storing various locations, and selecting one for the cellular module to use.

See also utCell.c , which uses the system implemented here.

Author

Oscar Key

Date

07/09/2012

Copyright

2012, Igtimi Ltd., all rights reserved.

Macro Definition Documentation

DEFAULT_INDEX

#define DEFAULT_INDEX   0

The array index the default server location is stored in. Review logic before trying to change this. The default server location is data.igtimi.com:1212.

MAX_USERVE_LOCATIONS

#define MAX_USERVE_LOCATIONS   USER_USERVE_LOCATIONS + 1

The maximum number server locations to store, typically the maximum number of user-defined locations plus the default location. Does not include the override location.

MIN_USEFUL_LINE_LEN

#define MIN_USEFUL_LINE_LEN   15 - 1

The minimum number of characters needed to make up a valid line to parse.

REQ_ITEMS_PER_LINE

#define REQ_ITEMS_PER_LINE   2

The required number of key:value pairs (items) in a valid line to parse.

USER_USERVE_LOCATIONS

#define USER_USERVE_LOCATIONS   3

The maximum number of user-defined server locations that can be stored, not including the override location.

Enumeration Type Documentation

UT_ITEM_TYPE

enum UT_ITEM_TYPE

Expected key:value pair types. Used in the parser.

Function Documentation

utServerLocation_ClearOverride()

void utServerLocation_ClearOverride

(

void

)

Clears the override location, removing it and unsetting the current location

utServerLocation_Fallback()

void utServerLocation_Fallback

(

void

)

Requests that the server location system fallback to the next server location, if possible. This is not possible if the override location has been set (it overrides all other functionality), or if the default location is disabled but there are no other stored locations.

utServerLocation_GetDefaultAllowed()

bool utServerLocation_GetDefaultAllowed

(

void

)

Gets whether or not the default usServer location is enabled.

Returns

Whether or not use of the default uServerlocation is allowed.

utServerLocation_GetDNS()

const char * utServerLocation_GetDNS

(

void

)

Gets the DNS address of the current location if possible.

Returns

A pointer to the current location's DNS address as a string if it exists, else null.

utServerLocation_GetIP()

const char * utServerLocation_GetIP

(

void

)

Gets the IP address of the current location if possible.

Returns

A pointer to the current location's IP address as a string if it exists, else null.

utServerLocation_GetOverrideAddress()

const char * utServerLocation_GetOverrideAddress

(

void

)

Gets the override address if possible.

Returns

A pointer to the override address, as a string, if possible, else null.

utServerLocation_GetOverridePort()

int utServerLocation_GetOverridePort

(

void

)

Gets the port for the override location if possible.

Returns

The port for the override location if possible, else -1.

utServerLocation_GetPort()

int utServerLocation_GetPort

(

void

)

Gets the port for the current location if possible.

Returns

The port for the current location if possible, else -1.

utServerLocation_HandleLine()

bool utServerLocation_HandleLine	(	const char *	line,
		u8	lineLength
	)

HandleLine parses a line of the uServer server location list retrieved http://www.igtimi.com/bot_server/UNIT_ID/MajorVersion.MinorVersion.Build/ using HTTP GET.

Parameters

line	The line to parse.
lineLength	The length, in characters, of the line.

Returns

True if the line contained a correctly formatted location, else false.

utServerLocation_HasDNS()

bool utServerLocation_HasDNS

(

void

)

Used to determine whether the current uServe location has a stored DNS address.

Returns

If the current uServe location has an DNS address or not.

utServerLocation_HasIP()

bool utServerLocation_HasIP

(

void

)

Used to determine whether the current uServe location has a stored IP address.

Returns

If the current uServe location has an IP address or not.

utServerLocation_IsOverridden()

bool utServerLocation_IsOverridden

(

void

)

Used to determine if the override is being used.

Returns

Whether or not the override location is currently active.

utServerLocation_SetDefaultAllowed()

void utServerLocation_SetDefaultAllowed

(

bool

allowed

)

Enables or disables use of the default uServe location.

Parameters

allowed

Whether to allow or forbid use of the default location

utServerLocation_SetIP()

void utServerLocation_SetIP	(	const char *	inf,
		u8	length
	)

Stores an IP address for the current location if possible. Typically used after the DNS for the current location has been resolved to an IP address.

Parameters

inf	The address to store.
length	The length, in characters, of the address string.

utServerLocation_SetOverrideLocation()

void utServerLocation_SetOverrideLocation	(	const char *	address,
		bool	isIP,
		u16	port
	)

Sets an override server location. This overrides all other functionality.

Parameters

address	The address of the override server location.
isIP	Whether or not address is an IP address. If address is not null and isIP is false, address is assumed to be a DNS address.
port	The port to set.