#include <serial_listener.h>

Public Member Functions
BlockingFilterPtr	createBlockingFilter (ComparatorType comparator)
BufferedFilterPtr	createBufferedFilter (ComparatorType comparator, size_t buffer_size=1024)
FilterPtr	createFilter (ComparatorType comparator, DataCallback callback)
bool	isListening ()
void	removeAllFilters ()
void	removeFilter (FilterPtr filter_ptr)
void	removeFilter (BlockingFilterPtr blocking_filter)
void	removeFilter (BufferedFilterPtr buffered_filter)
	SerialListener (size_t num_threads=0)
void	setChunkSize (size_t chunk_size)
void	setDefaultHandler (DataCallback default_handler)
void	setExceptionHandler (ExceptionCallback exception_handler)
void	setTokenizer (TokenizerType tokenizer)
void	startListening (serial::Serial &serial_port)
void	stopListening ()
virtual	~SerialListener ()
Static Public Member Functions
static ComparatorType	contains (std::string substr)
static TokenizerType	delimeter_tokenizer (std::string delimeter)
static ComparatorType	endsWith (std::string postfix)
static ComparatorType	exactly (std::string exact_str)
static void	sleep (long milliseconds)
static ComparatorType	startsWith (std::string prefix)
Private Member Functions
void	callback (size_t)
void	default_handler (const std::string &token)
size_t	determineAmountToRead ()
void	filter (std::vector< TokenPtr > &tokens)
void	listen ()
void	operator= (const SerialListener &)
const SerialListener &	operator= (SerialListener)
void	readSomeData (std::string &temp, size_t this_many)
	SerialListener (const SerialListener &)
Static Private Member Functions
static bool	_contains (const std::string &token, std::string substr)
static void	_delimeter_tokenizer (const std::string &data, std::vector< TokenPtr > &tokens, std::string delimeter)
static bool	_endsWith (const std::string &token, std::string postfix)
static bool	_exactly (const std::string &token, std::string exact_str)
static bool	_startsWith (const std::string &token, std::string prefix)
Private Attributes
DataCallback	_default_handler
ConcurrentQueue< std::pair < FilterPtr, TokenPtr > >	callback_queue
std::vector< boost::thread * >	callback_threads
size_t	chunk_size_
std::string	data_buffer
ComparatorType	default_comparator
FilterPtr	default_filter
boost::mutex	filter_mux
std::vector< FilterPtr >	filters
ExceptionCallback	handle_exc
boost::thread	listen_thread
bool	listening
size_t	num_threads_
serial::Serial *	serial_port_
char	serial_port_padding [7]
TokenizerType	tokenize

Detailed Description

Listens to a serial port, facilitates asynchronous reading

Definition at line 229 of file serial_listener.h.

Constructor & Destructor Documentation

SerialListener::SerialListener ( size_t num_threads = 0 )

Creates a new Serial Listener.

Definition at line 27 of file serial_listener.cc.

SerialListener::~SerialListener ( ) [virtual]

Destructor.

Definition at line 53 of file serial_listener.cc.

serial::utils::SerialListener::SerialListener ( const SerialListener & ) [private]

Member Function Documentation

static bool serial::utils::SerialListener::_contains	(	const std::string &	token,
		std::string	substr
	)		`[inline, static, private]`

Definition at line 647 of file serial_listener.h.

static void serial::utils::SerialListener::_delimeter_tokenizer	(	const std::string &	data,
		std::vector< TokenPtr > &	tokens,
		std::string	delimeter
	)		`[inline, static, private]`

Definition at line 590 of file serial_listener.h.

static bool serial::utils::SerialListener::_endsWith	(	const std::string &	token,
		std::string	postfix
	)		`[inline, static, private]`

Definition at line 631 of file serial_listener.h.

static bool serial::utils::SerialListener::_exactly	(	const std::string &	token,
		std::string	exact_str
	)		`[inline, static, private]`

Definition at line 602 of file serial_listener.h.

static bool serial::utils::SerialListener::_startsWith	(	const std::string &	token,
		std::string	prefix
	)		`[inline, static, private]`

Definition at line 616 of file serial_listener.h.

void SerialListener::callback ( size_t thread_index ) [private]

Definition at line 60 of file serial_listener.cc.

static ComparatorType serial::utils::SerialListener::contains ( std::string substr ) [inline, static]

This returns a comparator that looks for a given substring in the token.

This can be used with listenFor or listenForOnce:

Example:

   my_listener.listenFor(SerialListener::contains("some string"),
                         my_callback);
 <
Precondition:
>
 Parameters:

  
    substr A std::string that is used as the search substring to match
 when comparing tokens for matching.
  
  

 Returns:
 ComparatorType A comparator function type that can be passed to
 SerialListener::listenFor or SerialListener::listenForOnce.
 See also:
 SerialListener::listenFor, SerialListener::listenForOnce,
 serial::ComparatorType

Definition at line 579 of file serial_listener.h.

BlockingFilterPtr SerialListener::createBlockingFilter ( ComparatorType comparator )

Creates a BlockingFilter which blocks until the comparator returns true.

The user provides a comparator, and every time a line is received the comparator is called and the comparator has to evaluate the line and return true if it matches and false if it doesn't. If it does match, any threads that have called BlockingFilter::wait will be notified. The BlockingFilter will remove itself when its destructor is called, i.e. when it leaves the scope, so in those cases an explicit call to SerialListener::removeFilter is not needed.

Parameters:

comparator This is a comparator for detecting if a line matches. The comparartor receives a std::string reference and must return a true if it matches and false if it doesn't.

Returns:: BlockingFilterPtr So you can call BlockingFilter::wait on it.

See also:: SerialListener::removeFilter, serial::BlockingFilter, serial::BlockingFilterPtr

Definition at line 205 of file serial_listener.cc.

BufferedFilterPtr SerialListener::createBufferedFilter	(	ComparatorType	comparator,
		size_t	buffer_size = `1024`
	)

Creates a BlockingFilter blocks until the comparator returns true.

The user provides a comparator, and every time a line is received the comparator is called and the comparator has to evaluate the line and return true if it matches and false if it doesn't. If it does match, any threads that have called BlockingFilter::wait will be notified. The BlockingFilter will remove itself when its destructor is called, i.e. when it leaves the scope, so in those cases an explicit call to SerialListener::removeFilter is not needed.

Parameters:

comparator	This is a comparator for detecting if a line matches. The comparartor receives a std::string reference and must return a true if it matches and false if it doesn't.
buffer_size	This is the number of tokens to be buffered by the BufferedFilter, defaults to 1024.

Returns:: BlockingFilter So you can call BlockingFilter::wait on it.

See also:: SerialListener::removeFilter, serial::BufferedFilter, serial::BufferedFilterPtr

Definition at line 211 of file serial_listener.cc.

FilterPtr SerialListener::createFilter	(	ComparatorType	comparator,
		DataCallback	callback
	)

Creates a filter that calls a callback when the comparator returns true.

The user provides a comparator and a callback, and every time a line is received the comparator is called and the comparator has to evaluate the line and return true if it matches and false if it doesn't. If it does match, the callback is called with the resulting line.

Parameters:

comparator	This is a comparator for detecting if a line matches. The comparartor receives a std::string reference and must return a true if it matches and false if it doesn't.
callback	This is the handler for when a match occurs. It is given a std::string reference of the line that matched your comparator.

Returns:: boost::shared_ptr<Filter> so you can remove it later.

See also:: SerialListener::removeFilter

Definition at line 194 of file serial_listener.cc.

void SerialListener::default_handler ( const std::string & token ) [private]

Definition at line 22 of file serial_listener.cc.

static TokenizerType serial::utils::SerialListener::delimeter_tokenizer ( std::string delimeter ) [inline, static]

This returns a tokenizer that splits on a given delimeter.

The delimeter is passed into the function and a TokenizerType is returned that can be passed to SerialListener::setTokenizer.

Example:

   my_listener.setTokenizer(SerialListener::delimeter_tokenizer("\r"));
 <
Precondition:
>
 Parameters:

  
    delimeter A std::string that is used as a delimeter when
 tokenizing data.
  
  

 Returns:
 TokenizerType A tokenizer function type that can be passed to
 SerialListener::setTokenizer.
 See also:
 SerialListener::setTokenizer, serial::TokenizerType

Definition at line 480 of file serial_listener.h.

size_t SerialListener::determineAmountToRead ( ) [private]

Definition at line 125 of file serial_listener.cc.

static ComparatorType serial::utils::SerialListener::endsWith ( std::string postfix ) [inline, static]

This returns a comparator that looks for a given postfix.

This can be used with listenFor or listenForOnce:

Example:

   my_listener.listenFor(SerialListener::endsWith(";"), my_callback);
 <
Precondition:
>
 Parameters:

  
    postfix A std::string that is used as the postfix string to match
 when comparing tokens for matching.
  
  

 Returns:
 ComparatorType A comparator function type that can be passed to
 SerialListener::listenFor or SerialListener::listenForOnce.
 See also:
 SerialListener::listenFor, SerialListener::listenForOnce,
 serial::ComparatorType

Definition at line 554 of file serial_listener.h.

static ComparatorType serial::utils::SerialListener::exactly ( std::string exact_str ) [inline, static]

This returns a comparator that matches only the exact string given.

This can be used with listenFor or listenForOnce:

Example:

   my_listener.listenFor(SerialListener::exactly("my_string"),
                         my_callback);
 <
Precondition:
>
 Parameters:

  
    exact_str A std::string that is used as the exact string to match
 when comparing tokens for matching.
  
  

 Returns:
 ComparatorType A comparator function type that can be passed to
 SerialListener::listenFor or SerialListener::listenForOnce.
 See also:
 SerialListener::listenFor, SerialListener::listenForOnce,
 serial::ComparatorType

Definition at line 506 of file serial_listener.h.

void SerialListener::filter ( std::vector< TokenPtr > & tokens ) [private]

Definition at line 133 of file serial_listener.cc.

bool serial::utils::SerialListener::isListening ( ) [inline]

Returns true if currently listening, false oterhwise.

Definition at line 295 of file serial_listener.h.

void SerialListener::listen ( ) [private]

Definition at line 163 of file serial_listener.cc.

void serial::utils::SerialListener::operator= ( const SerialListener & ) [private]

const SerialListener& serial::utils::SerialListener::operator= ( SerialListener ) [private]

void serial::utils::SerialListener::readSomeData	(	std::string &	temp,
		size_t	this_many
	)		`[inline, private]`

Definition at line 663 of file serial_listener.h.

void SerialListener::removeAllFilters ( )

Removes all filters.

Definition at line 235 of file serial_listener.cc.

void SerialListener::removeFilter ( FilterPtr filter_ptr )

Removes a filter by a given FilterPtr.

Parameters:

filter_ptr A shared pointer to the filter to be removed.

See also:: SerialListener::createFilter

Definition at line 219 of file serial_listener.cc.

void SerialListener::removeFilter ( BlockingFilterPtr blocking_filter )

Removes a BlockingFilter.

The BlockingFilter will remove itself if the destructor is called.

Parameters:

blocking_filter A BlockingFilter to be removed.

See also:: SerialListener::createBlockingFilter

Definition at line 225 of file serial_listener.cc.

void SerialListener::removeFilter ( BufferedFilterPtr buffered_filter )

Removes a BufferedFilter.

The BufferedFilter will remove itself if the destructor is called.

Parameters:

buffered_filter A BufferedFilter to be removed.

See also:: SerialListener::createBufferedFilter

Definition at line 230 of file serial_listener.cc.

void serial::utils::SerialListener::setChunkSize ( size_t chunk_size ) [inline]

Sets the number of bytes to be read at a time by the listener.

Parameters:

chunk_size Number of bytes to be read at a time.

Definition at line 267 of file serial_listener.h.

void serial::utils::SerialListener::setDefaultHandler ( DataCallback default_handler ) [inline]

Sets the handler to be called when a lines is not caught by a filter.

This allows you to set a catch all function that will get called everytime a line is not matched by a filter and the ttl expires.

Setting the callbacks works just like SerialListener::setInfoHandler.

Parameters:

default_handler A function pointer to the callback to handle unmatched and expired messages.

See also:: serial::DataCallback, SerialListener::setInfoHandler

Definition at line 427 of file serial_listener.h.

void serial::utils::SerialListener::setExceptionHandler ( ExceptionCallback exception_handler ) [inline]

Sets the function to be called when an exception occurs internally.

This allows you to hook into the exceptions that occur in threads inside the serial listener library.

Parameters:

exception_handler A function pointer to the callback to handle new interal exceptions.

See also:: serial::ExceptionCallback

Definition at line 443 of file serial_listener.h.

void serial::utils::SerialListener::setTokenizer ( TokenizerType tokenizer ) [inline]

Sets the tokenizer to be used when tokenizing the data into tokens.

This function is given a std::string of data and is responsible for tokenizing that data into a std::vector<TokenPtr> of data tokens. The default tokenizer splits the data by the ascii return carriage. The user can create their own tokenizer or use one of the default ones.

Parameters:

tokenizer Function for tokenizing the incoming data.

See also:: serial::TokenizerType, serial::delimeter_tokenizer

Definition at line 257 of file serial_listener.h.

static void serial::utils::SerialListener::sleep ( long milliseconds ) [inline, static]

Sleeps for a given number of milliseconds.

Parameters:

milliseconds number of milliseconds to sleep.

Definition at line 455 of file serial_listener.h.

void SerialListener::startListening ( serial::Serial & serial_port )

Starts a thread to listen for messages and process them through filters.

Parameters:

serial_port Pointer to a serial::Serial object that is used to retrieve new data.

Definition at line 82 of file serial_listener.cc.

static ComparatorType serial::utils::SerialListener::startsWith ( std::string prefix ) [inline, static]

This returns a comparator that looks for a given prefix.

This can be used with listenFor or listenForOnce:

Example:

   my_listener.listenFor(SerialListener::startsWith("V="), my_callback);
 <
Precondition:
>
 Parameters:

  
    prefix A std::string that is used as the prefix string to match
 when comparing tokens for matching.
  
  

 Returns:
 ComparatorType A comparator function type that can be passed to
 SerialListener::listenFor or SerialListener::listenForOnce.
 See also:
 SerialListener::listenFor, SerialListener::listenForOnce,
 serial::ComparatorType