.\" Copyright (C) 2010 Romain Tartiere
.\"
.\" This program is free software: you can redistribute it and/or modify it
.\" under the terms of the GNU Lesser 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 Lesser General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>
.\"
.\" $Id$
.\"
.Dd March 30, 2010
.Dt FREEFARE 3
.Os
.\"  _   _
.\" | \ | | __ _ _ __ ___   ___
.\" |  \| |/ _` | '_ ` _ \ / _ \
.\" | |\  | (_| | | | | | |  __/
.\" |_| \_|\__,_|_| |_| |_|\___|
.\"
.Sh NAME
.Nm freefare_get_tags ,
.Nm freefare_get_tag_type ,
.Nm freefare_get_tag_friendly_name ,
.Nm freefare_get_tag_uid ,
.Nm freefare_free_tag ,
.Nm freefare_free_tags
.Nd Generic target manipulation functions
.\"  _     _ _
.\" | |   (_) |__  _ __ __ _ _ __ _   _
.\" | |   | | '_ \| '__/ _` | '__| | | |
.\" | |___| | |_) | | | (_| | |  | |_| |
.\" |_____|_|_.__/|_|  \__,_|_|   \__, |
.\"                               |___/
.Sh LIBRARY
Mifare card manipulation library (libfreefare, \-lfreefare)
.\"  ____                              _
.\" / ___| _   _ _ __   ___  _ __  ___(_)___
.\" \___ \| | | | '_ \ / _ \| '_ \/ __| / __|
.\"  ___) | |_| | | | | (_) | |_) \__ \ \__ \
.\" |____/ \__, |_| |_|\___/| .__/|___/_|___/
.\"        |___/            |_|
.Sh SYNOPSIS
.In freefare.h
.Ft "MifareTag *"
.Fn freefare_get_tags "nfc_device_t *device"
.Bd -literal
enum mifare_tag_type {
    ULTRALIGHT,
    CLASSIC_1K,
    CLASSIC_4K
};
.Ed
.Ft "enum mifare_tag_type"
.Fn freefare_get_tag_type "MifareTag tag"
.Ft "const char *"
.Fn freefare_get_tag_friendly_name "MifareTag tag"
.Ft "char *"
.Fn freefare_get_tag_uid "MifareTag tag"
.Ft "void"
.Fn freefare_free_tag "MifareTag tags"
.Ft "void"
.Fn freefare_free_tags "MifareTag *tags"
.\"  ____                      _       _   _
.\" |  _ \  ___  ___  ___ _ __(_)_ __ | |_(_) ___  _ __
.\" | | | |/ _ \/ __|/ __| '__| | '_ \| __| |/ _ \| '_ \
.\" | |_| |  __/\__ \ (__| |  | | |_) | |_| | (_) | | | |
.\" |____/ \___||___/\___|_|  |_| .__/ \__|_|\___/|_| |_|
.\"                             |_|
.Sh DESCRIPTION
The
.Fn freefare_*
family of functions allow agnostic access to the
.Vt MifareTag
present on a given NFC device.
.Pp
.Fn freefare_get_tags
returns a NULL-terminated list of
.Vt MifareTag
present on
.Vt device .
This list has to be freed after usage by either:
.Bl -hyphen
.It
calling the
.Fn freefare_free_tags
function.  All tags in the list are automatically freed;
.It
calling the
.Fn freefare_free_tag
function to free each tag in the list individually, and freeing the list itself
using the
.Fn free
function.
.El
.Pp
Because of the nature of the target detection process, any previously detected
target will be in an inconsistent state after a call to
.Fn freefare_get_tags .
It is the programmer's responsibility to free these targets before calling the
.Fn freefare_get_tags
function.
.Pp
Information about a given
.Vt MifareTag
can be gathered using the
.Fn freefare_get_tag_type ,
.Fn freefare_get_tag_uid
and
.Fn freefare_get_tag_friendly_name
functions.
.\"  ____      _                                 _
.\" |  _ \ ___| |_ _   _ _ __ _ __   __   ____ _| |_   _  ___  ___
.\" | |_) / _ \ __| | | | '__| '_ \  \ \ / / _` | | | | |/ _ \/ __|
.\" |  _ <  __/ |_| |_| | |  | | | |  \ V / (_| | | |_| |  __/\__ \
.\" |_| \_\___|\__|\__,_|_|  |_| |_|   \_/ \__,_|_|\__,_|\___||___/
.\"
.Sh RETURN VALUES
Unless stated otherwise, all functions return a value greater than or equal to
.Va 0
on success or
.Va -1
on failure.
.\"  ____                    _
.\" / ___|  ___  ___    __ _| |___  ___
.\" \___ \ / _ \/ _ \  / _` | / __|/ _ \
.\"  ___) |  __/  __/ | (_| | \__ \ (_) |
.\" |____/ \___|\___|  \__,_|_|___/\___/
.\"
.Sh SEE ALSO
.Xr free 3 ,
.Xr mifare_classic 3 ,
.Xr mifare_ultralight 3
.\"     _         _   _
.\"    / \  _   _| |_| |__   ___  _ __ ___
.\"   / _ \| | | | __| '_ \ / _ \| '__/ __|
.\"  / ___ \ |_| | |_| | | | (_) | |  \__ \
.\" /_/   \_\__,_|\__|_| |_|\___/|_|  |___/
.\"
.Sh AUTHORS
.An Romain Tartiere Aq romain@blogreen.org
.An Romuald Conty Aq romuald@libnfc.org