.\" 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 MIFARE_APPLICATION 3
.Os
.\"  _   _
.\" | \ | | __ _ _ __ ___   ___
.\" |  \| |/ _` | '_ ` _ \ / _ \
.\" | |\  | (_| | | | | | |  __/
.\" |_| \_|\__,_|_| |_| |_|\___|
.\"
.Sh NAME
.Nm mifare_application_alloc ,
.Nm mifare_application_find ,
.Nm mifare_application_free ,
.Nm mifare_application_read ,
.Nm mifare_application_write
.Nd Mifare Applications Manipulation Functions
.\"  _     _ _
.\" | |   (_) |__  _ __ __ _ _ __ _   _
.\" | |   | | '_ \| '__/ _` | '__| | | |
.\" | |___| | |_) | | | (_| | |  | |_| |
.\" |_____|_|_.__/|_|  \__,_|_|   \__, |
.\"                               |___/
.Sh LIBRARY
Mifare card manipulation library (libfreefare, \-lfreefare)
.\"  ____                              _
.\" / ___| _   _ _ __   ___  _ __  ___(_)___
.\" \___ \| | | | '_ \ / _ \| '_ \/ __| / __|
.\"  ___) | |_| | | | | (_) | |_) \__ \ \__ \
.\" |____/ \__, |_| |_|\___/| .__/|___/_|___/
.\"        |___/            |_|
.Sh SYNOPSIS
.In freefare.h
.Ft "MifareClassicSectorNumber *"
.Fn mifare_application_alloc "Mad mad" "MadAid aid" "size_t size"
.Ft "void"
.Fn mifare_application_free "Mad mad" "MadAid aid"
.Ft "MifareClassicSectorNumber *"
.Fn mifare_application_find "Mad mad" "MadAid aid"
.Ft "ssize_t"
.Fn mifare_application_read "MifareTag tag" "Mad mad" "MadAid aid" "void *buf" "size_t nbytes" "MifareClassicKey key" "MifareClassicKeyType key_type"
.Ft "ssize_t"
.Fn mifare_application_write "MifareTag tag" "Mad mad" "MadAid aid" "const void *buf" "size_t nbytes" "MifareClassicKey key" "MifareClassicKeyType key_type"
.\"  ____                      _       _   _
.\" |  _ \  ___  ___  ___ _ __(_)_ __ | |_(_) ___  _ __
.\" | | | |/ _ \/ __|/ __| '__| | '_ \| __| |/ _ \| '_ \
.\" | |_| |  __/\__ \ (__| |  | | |_) | |_| | (_) | | | |
.\" |____/ \___||___/\___|_|  |_| .__/ \__|_|\___/|_| |_|
.\"                             |_|
.Sh DESCRIPTION
The
.Fn mifare_application_*
functions facilitate management of applications in a Mifare Application
Directory.
.Pp
The
.Fn mifare_application_alloc
function allocates enought sectors to store
.Vt size
bytes for the Application Identifier
.Vt aid
and returns the list of allocated sectors.
.Pp
The list of the sectors previously allocated for
.Vt aid
in a
.Vt mad
can be requested using
.Fn mifare_application_find .
.Pp
An application can be removed from a
.Vt mad
using
.Fn mifare_application_free .
.Pp
The
.Fn mifare_application_read
reads at most
.Vt nbytes
of the application identified by
.Vt aid
in the
.Vt mad
on the
.Vt tag
and copy them into
.Vt buf.
The function returns the amount of data it copied, or \-1 on error.
.Pp
The
.Fn mifare_application_write
functions writes at most
.Vt nbytes
of
.Vt buf
in the application identified by
.Vt aid
on the
.Vt mad
of the
.Vt tag
and returns the quantity of data written, or \-1 on error.
.\"  ___                 _                           _        _   _                           _            
.\" |_ _|_ __ ___  _ __ | | ___ _ __ ___   ___ _ __ | |_ __ _| |_(_) ___  _ __    _ __   ___ | |_ ___  ___ 
.\"  | || '_ ` _ \| '_ \| |/ _ \ '_ ` _ \ / _ \ '_ \| __/ _` | __| |/ _ \| '_ \  | '_ \ / _ \| __/ _ \/ __|
.\"  | || | | | | | |_) | |  __/ | | | | |  __/ | | | || (_| | |_| | (_) | | | | | | | | (_) | ||  __/\__ \
.\" |___|_| |_| |_| .__/|_|\___|_| |_| |_|\___|_| |_|\__\__,_|\__|_|\___/|_| |_| |_| |_|\___/ \__\___||___/
.\"               |_|                                                                                      
.Sh IMPLEMENTATION NOTES
The
.Fn mifare_application_alloc
function will try to avoid wasting space and might not allocate sectors
sequentially if a large amount of space is requested and the target has sectors
of different size.
.Pp
The
.Vt nbytes
argument of
.Fn mifare_application_read
and
.Fn mifare_application_write
does not need to be aligned on blocks not sectors.
.\"  ____      _                                 _
.\" |  _ \ ___| |_ _   _ _ __ _ __   __   ____ _| |_   _  ___  ___
.\" | |_) / _ \ __| | | | '__| '_ \  \ \ / / _` | | | | |/ _ \/ __|
.\" |  _ <  __/ |_| |_| | |  | | | |  \ 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 mad 3 ,
.Xr mifare_classic 3
.\"     _         _   _
.\"    / \  _   _| |_| |__   ___  _ __ ___
.\"   / _ \| | | | __| '_ \ / _ \| '__/ __|
.\"  / ___ \ |_| | |_| | | | (_) | |  \__ \
.\" /_/   \_\__,_|\__|_| |_|\___/|_|  |___/
.\"
.Sh AUTHORS
.An Romain Tartiere Aq romain@blogreen.org
.An Romuald Conty Aq romuald@libnfc.org