.\" libxbee - a C library to aid the use of Digi's Series 1 XBee modules
.\"           running in API mode (AP=2).
.\" 
.\" Copyright (C) 2009  Attie Grande (attie@attie.co.uk)
.\" 
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.TH XBEE_GETPACKET 3  2009-11-01 "GNU" "Linux Programmer's Manual"
.SH NAME
xbee_getpacket, xbee_getpacketwait
.SH SYNOPSIS
.B #include <xbee.h>
.sp
.BI "xbee_pkt *xbee_getpacket(xbee_con *" con ");"
.sp
.BI "xbee_pkt *xbee_getpacketwait(xbee_con *" con ");"
.ad b
.SH DESCRIPTION
The
.BR xbee_getpacket ()
function will return the next avaliable packet for the provided connection.
It takes 1 argument.
.sp
The argument
.I con
points to a connection made previously with
.BR xbee_newcon ().
.sp
The
.BR xbee_getpacketwait ()
function behaves the same, but will wait for an internally specified time for a packet to arrive (currently around 1 second).
.SH "RETURN VALUE"
Upon successful return, this function returns the packet, having unlinked it from the internal list.
You must keep hold of the packet until you are finished with it, and then you must
.BR free ()
it to prevent memory leaks.
.sp
If a packet was not avaliable for the provided connection, a
.B NULL
is returned.
.sp
If an error occured a
.B NULL
is also returned (though unlikely).
.sp
For more information on the structure of the packet, please see
.BR xbee_pkt (3)
.sp
For information on using callback functions with connections instead, please see
.BR xbee_con (3)
or
.B callback.c
in the SVN sample directory.
.SH EXAMPLE
To recieve a packet from a previously made connection:
.in +4n
.nf
#include <xbee.h>
xbee_pkt *pkt;
if ((pkt = xbee_getpacket(con)) != NULL) {
  /* process packet... */
  free(pkt);
}
.fi
.in
.SH AUTHOR
Attie Grande <attie@attie.co.uk> 
.SH "SEE ALSO"
.BR libxbee (3),
.BR xbee_setup (3),
.BR xbee_newcon (3),
.BR xbee_senddata (3),
.BR xbee_pkt (3),
.BR xbee_con (3),
.BR xbee_hasDigital (3),
.BR xbee_getDigital (3),
.BR xbee_hasAnalog (3),
.BR xbee_getAnalog (3)