giomba
/
opensc
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Documentation: there is no external API, remove the manpage generation. 

git-svn-id: https://www.opensc-project.org/svnp/opensc/trunk@4407 c6295689-39f2-0310-b995-f0e70906c6a9
This commit is contained in:
martin 2010-06-09 13:39:28 +00:00
parent 8737ace703
commit 14d82f9e4c
68 changed files with 0 additions and 3095 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/api/api.xml
View File

@ -1,18 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY includes "#include &lt;opensc.h&gt;">
]>
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<title>OpenSC API reference</title>
<xi:include href="init/chapter.xml"/>
<xi:include href="card/chapter.xml"/>
<xi:include href="file/chapter.xml"/>
<xi:include href="apps/chapter.xml"/>
<xi:include href="asn1/chapter.xml"/>
<xi:include href="util/chapter.xml"/>
<xi:include href="types/chapter.xml"/>
</book>

20
doc/api/apps/chapter.xml
View File

@ -1,20 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY scfreeapps SYSTEM "sc_free_apps.xml">
<!ENTITY scfindappbyaid SYSTEM "sc_find_app_by_aid.xml">
<!ENTITY scupdatedir SYSTEM "sc_update_dir.xml">
<!ENTITY scenumapps SYSTEM "sc_enum_apps.xml">
<!ENTITY scfindpkcs15app SYSTEM "sc_find_pkcs15_app.xml">
]>
<chapter>
<title>Applications</title>
&scenumapps;
&scfindappbyaid;
&scfindpkcs15app;
&scupdatedir;
&scfreeapps;
</chapter>

43
doc/api/apps/sc_enum_apps.xml
View File

@ -1,43 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scenumapps">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_enum_apps</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_enum_apps</refname>
<refpurpose>Enumerate the applications on a card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_enum_apps(struct sc_card *card);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function enumerates the applications on <emphasis>card</emphasis>, and
stores them in the structure. The list of applications can then later be
searched with <link linkend="scfindappbyaid">sc_find_app_by_aid()</link> or
<link linkend="scfindpkcs15app">sc_find_pkcs15_app()</link>.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns the number of applications on the card, or a negative value in case
of error.
</para>
</refsect1>
</refentry>

50
doc/api/apps/sc_find_app_by_aid.xml
View File

@ -1,50 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scfindappbyaid">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_find_app_by_aid</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_find_app_by_aid</refname>
<refpurpose>Find an application on a card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
const sc_app_info_t *sc_find_app_by_aid(sc_card_t *card,
const unsigned char *aid,
size_t aid_len);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function finds an application on <emphasis>card</emphasis> by its
<emphasis>aid</emphasis>. The AID's length is specified in
<emphasis>aid_len</emphasis>.
</para>
<para>
Before calling this function, you MUST call <link
linkend="scenumapps">sc_enum_apps()</link> first.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns a <link linkend="scappinfot">sc_app_info_t</link> structure
describing the application corresponding to <emphasis>aid</emphasis>, or NULL
if none was found.
</para>
</refsect1>
</refentry>

47
doc/api/apps/sc_find_pkcs15_app.xml
View File

@ -1,47 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scfindpkcs15app">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_find_pkcs15_app</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_find_pkcs15_app</refname>
<refpurpose>Find a PKCS#15 application on a card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
const sc_app_info_t *sc_find_pkcs15_app(sc_card_t *card);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function attempts to find a PKCS#15 application on
<emphasis>card</emphasis>. Currently, this means either a standard PKCS#15
implementation or a Belgian eID.
</para>
<para>
Before calling this function, you MUST call <link
linkend="scenumapps">sc_enum_apps()</link> first.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns a <link linkend="scappinfot">sc_app_info_t</link> structure
describing the PKCS#15 application, or NULL if none was found.
</para>
</refsect1>
</refentry>

34
doc/api/apps/sc_free_apps.xml
View File

@ -1,34 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scfreeapps">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_free_apps</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_free_apps</refname>
<refpurpose>Free application list</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
void sc_free_apps(struct sc_card *card);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This functions releases all memory associated with the list of applications
on <emphasis>card</emphasis>, as obtained by a call to <link
linkend="scenumapps">sc_enum_apps()</link>.
</para>
</refsect1>
</refentry>

47
doc/api/apps/sc_update_dir.xml
View File

@ -1,47 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scupdatedir">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_update_dir</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_update_dir</refname>
<refpurpose>Update application directory on a card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_update_dir(sc_card_t *card, sc_app_info_t *app);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function updates the application directory on <emphasis>card</emphasis>.
If the card has a record-structured directory file, <emphasis>app</emphasis>
may contain the application to update. Otherwise, the entire directory file
is updated.
</para>
<para>
Before calling this function, you MUST call <link
linkend="scenumapps">sc_enum_apps()</link> first.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

31
doc/api/asn1/chapter.xml
View File

@ -1,31 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY scasn1encode SYSTEM "sc_asn1_encode.xml">
<!ENTITY scasn1decode SYSTEM "sc_asn1_decode.xml">
<!ENTITY scformatasn1entry SYSTEM "sc_format_asn1_entry.xml">
<!ENTITY sccopyasn1entry SYSTEM "sc_copy_asn1_entry.xml">
<!ENTITY scasn1printtags SYSTEM "sc_asn1_print_tags.xml">
<!ENTITY scasn1skiptag SYSTEM "sc_asn1_skip_tag.xml">
<!ENTITY scasn1verifytag SYSTEM "sc_asn1_verify_tag.xml">
<!ENTITY scasn1readtag SYSTEM "sc_asn1_read_tag.xml">
<!ENTITY scasn1findtag SYSTEM "sc_asn1_find_tag.xml">
<!ENTITY scasn1puttag SYSTEM "sc_asn1_put_tag.xml">
]>
<chapter>
<title>ASN.1 functions</title>
&scasn1encode;
&scasn1decode;
&scformatasn1entry;
&sccopyasn1entry;
&scasn1printtags;
&scasn1skiptag;
&scasn1verifytag;
&scasn1readtag;
&scasn1findtag;
&scasn1puttag;
</chapter>

62
doc/api/asn1/sc_asn1_decode.xml
View File

@ -1,62 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scasn1decode">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_asn1_decode</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_asn1_decode</refname>
<refpurpose>Extract entries from an ASN.1 stream</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_asn1_decode(struct sc_context *ctx, struct sc_asn1_entry *asn1,
const unsigned char *inbuf, size_t len,
const unsigned char **newbuf, size_t *len_left);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function extracts information from the ASN.1 stream pointed to by <emphasis>inbuf</emphasis>
(which is <emphasis>len</emphasis> bytes in size) and stores it into the array of
<link linkend="scasn1entry"><structname>struct sc_asn_1</structname></link> entries pointed to by
<emphasis>asn1</emphasis>. The array must be big enough to contain all the entries that will be
found, or an error will be flagged. The last entry in the array must be a NULL entry, i.e. the
<structfield>name</structfield> field must be set to NULL.
</para>
<para>
The structure of the expected data must be encoded in the entries in <emphasis>asn1</emphasis>
before calling this function; specifically the <structfield>name</structfield>,
<structfield>type</structfield>, <structfield>tag</structfield> and
<structfield>flags</structfield> fields must be filled in.
</para>
<para>
The function will then scan the stream and fill in the remaining fields.
<emphasis>newbuf</emphasis> will point to the byte immediately following the extracted record, and
<emphasis>len_left</emphasis> will contain the number of bytes left in the buffer. Thus, the
<emphasis>newbuf</emphasis> and <emphasis>len_left</emphasis> fields may be passed in to
sc_asn1_decode() again, as the <emphasis>inbuf</emphasis> and <emphasis>len</emphasis> parameters,
until <emphasis>len</emphasis> reaches 0.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

48
doc/api/asn1/sc_asn1_encode.xml
View File

@ -1,48 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scasn1encode">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_asn1_encode</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_asn1_encode</refname>
<refpurpose>Encode ASN.1 entries into a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_asn1_encode(struct sc_context *ctx, const struct sc_asn1_entry *asn1,
unsigned char **newbuf, size_t *size);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function encodes an array of entries pointed to by <emphasis>asn1</emphasis> and terminated
by a NULL entry (i.e. where the <structfield>name</structfield> field of the entry is NULL) into
a newly allocated buffer.
</para>
<para>
The new buffer containing the ASN.1 stream will be stored in <emphasis>newbuf</emphasis>, and the
size of this buffer is stored in <emphasis>size</emphasis>. The application must free this buffer
after use.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

44
doc/api/asn1/sc_asn1_find_tag.xml
View File

@ -1,44 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scasn1findtag">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_asn1_find_tag</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_asn1_find_tag</refname>
<refpurpose>Find a tag in an ASN.1 stream</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
const unsigned char *sc_asn1_find_tag(struct sc_context *ctx,
const unsigned char *buf, size_t buflen,
unsigned int tag_in, size_t *taglen_in);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function tries to find an ASN.1 tag matching <emphasis>tag_in</emphasis> in the buffer
pointed to by <emphasis>buf</emphasis>, which is of size <emphasis>buflen</emphasis>. The buffer
should contain a series of ASN.1 entries.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
If the specified tag was not found, NULL is returned. If found, the address where it was found is
returned, and <emphasis>taglen_in</emphasis> is set to the length of the found tag.
</para>
</refsect1>
</refentry>

33
doc/api/asn1/sc_asn1_print_tags.xml
View File

@ -1,33 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scasn1printtags">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_asn1_print_tags</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_asn1_print_tags</refname>
<refpurpose>Print an ASN.1 stream to stdout</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
void sc_asn1_print_tags(const unsigned char *buf, size_t buflen);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function prints the ASN.1 stream pointed to by <emphasis>buf</emphasis>, which is of size
<emphasis>buflen</emphasis>, to stdout. This is useful for debugging.
</para>
</refsect1>
</refentry>

48
doc/api/asn1/sc_asn1_put_tag.xml
View File

@ -1,48 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scasn1puttag">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_asn1_put_tag</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_asn1_put_tag</refname>
<refpurpose>Construct an ASN.1 entry in a buffer</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_asn1_put_tag(int tag, const unsigned char *data, int datalen,
unsigned char *out, int outlen, unsigned char **nextbuf);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function constructs a single entry in an ASN.1 stream, at the buffer pointed to by
<emphasis>out</emphasis> (which is <emphasis>outlen</emphasis> bytes long). The tag to be used
is in <emphasis>tag</emphasis>, and the entry payload is pointed to by <emphasis>data</emphasis>,
which is <emphasis>datalen</emphasis> bytes long.
</para>
<para>
If <emphasis>nextbuf</emphasis> is not NULL, it will be filled in with a pointer to the buffer
address immediately following the newly copied entry.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

44
doc/api/asn1/sc_asn1_read_tag.xml
View File

@ -1,44 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scasn1readtag">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_asn1_read_tag</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_asn1_read_tag</refname>
<refpurpose>Extract a tag from an ASN.1 entry</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_asn1_read_tag(const unsigned char **buf, size_t buflen,
unsigned int *cla_out, unsigned int *tag_out, size_t *taglen);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function extracts a tag from an ASN.1 entry at the buffer pointed to by
the pointer in <emphasis>buf</emphasis>. The buffer is <emphasis>buflen</emphasis> bytes long.
The tag class will be stored in <emphasis>cla_out</emphasis>, the tag itself in
<emphasis>tag_out</emphasis>, and the length of the extracted tag in
<emphasis>tag_len</emphasis>.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 1 if successful, or -1 in case of error.
</para>
</refsect1>
</refentry>

42
doc/api/asn1/sc_asn1_skip_tag.xml
View File

@ -1,42 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scasn1skiptag">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_asn1_skip_tag</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_asn1_skip_tag</refname>
<refpurpose></refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
const unsigned char *sc_asn1_skip_tag(struct sc_context *ctx,
const unsigned char **buf, size_t *buflen,
unsigned int tag_in, size_t *taglen_out);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para>
<para>
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
</para>
</refsect1>
</refentry>

34
doc/api/asn1/sc_asn1_verify_tag.xml
View File

@ -1,34 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scasn1verifytag">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_asn1_verify_tag</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_asn1_verify_tag</refname>
<refpurpose>Verify validity of an ASN.1 tag</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
const unsigned char *sc_asn1_verify_tag(struct sc_context *ctx,
const unsigned char *buf, size_t buflen,
unsigned int tag_in, size_t *taglen_out);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is an alias for the <link linkend="scasn1skiptag">sc_asn1_skip_tag()</link> function.
</para>
</refsect1>
</refentry>

36
doc/api/asn1/sc_copy_asn1_entry.xml
View File

@ -1,36 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="sccopyasn1entry">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_copy_asn1_entry</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_copy_asn1_entry</refname>
<refpurpose>Copy an ASN.1 entry</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
void sc_copy_asn1_entry(const struct sc_asn1_entry *src, struct sc_asn1_entry *dest);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function copies an array of <link linkend="scasn1entry"><structname>struct
sc_asn1_entry</structname></link> entries pointed to be <emphasis>src</emphasis> to
<emphasis>dest</emphasis>. The array must be NULL-terminated (that is, the last entry must have
its <structfield>name</structfield> field set to NULL). There must be enough space available in
<emphasis>dest</emphasis>.
</para>
</refsect1>
</refentry>

36
doc/api/asn1/sc_format_asn1_entry.xml
View File

@ -1,36 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scformatasn1entry">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_format_asn1_entry</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_format_asn1_entry</refname>
<refpurpose>Fill in an ASN.1 entry structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
void sc_format_asn1_entry(struct sc_asn1_entry *entry, void *parm, void *arg, int set_present);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function stores the <emphasis>parm</emphasis> and <emphasis>arg</emphasis> pointers in the
<link linkend="scasn1entry"><structname>struct sc_asn1_entry</structname></link>
<emphasis>entry</emphasis>. No checking is done. Since the pointers are copied directly, the
storage they point to must not be freed by the calling application until the entry itself is
destroyed.
</para>
</refsect1>
</refentry>

31
doc/api/card/chapter.xml
View File

@ -1,31 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY sccardctl SYSTEM "sc_card_ctl.xml">
<!ENTITY sclock SYSTEM "sc_lock.xml">
<!ENTITY scunlock SYSTEM "sc_unlock.xml">
<!ENTITY scformatapdu SYSTEM "sc_format_apdu.xml">
<!ENTITY sctransmitapdu SYSTEM "sc_transmit_apdu.xml">
<!ENTITY scchecksw SYSTEM "sc_check_sw.xml">
<!ENTITY scgetchallenge SYSTEM "sc_get_challenge.xml">
<!ENTITY scgetdata SYSTEM "sc_get_data.xml">
<!ENTITY scputdata SYSTEM "sc_put_data.xml">
<!ENTITY scwaitforevent SYSTEM "sc_wait_for_event.xml">
]>
<chapter>
<title>Card operations</title>
&sccardctl;
&sclock;
&scunlock;
&scwaitforevent;
&scformatapdu;
&sctransmitapdu;
&scchecksw;
&scgetchallenge;
&scgetdata;
&scputdata;
</chapter>

46
doc/api/card/sc_card_ctl.xml
View File

@ -1,46 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="sccardctl">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_card_ctl</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_card_ctl</refname>
<refpurpose>Send a control command to a card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_card_ctl(struct sc_card *card, unsigned long cmd, void *args);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>This function is used to send various control commands to the smart card associated with
<emphasis>card</emphasis>. The command is specified in <emphasis>cmd</emphasis>, and any
command-specific arguments are pointed to by <emphasis>args</emphasis>.
</para>
<para>
Commands are specific to cards. For more details on which cards accept which
commands, check the documentation for your card.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

49
doc/api/card/sc_check_sw.xml
View File

@ -1,49 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scchecksw">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_check_sw</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_check_sw</refname>
<refpurpose>Check return status from a card transaction</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_check_sw(struct sc_card *card, int sw1, int sw2);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function checks the return status as given in <emphasis>sw1</emphasis>
and <emphasis>sw2</emphasis> against the card-specific errors of
<emphasis>card</emphasis>. These are set by <link
linkend="sctransmitapdu">sc_transmit_apdu()</link> in the
<structfield>apdu.sw1</structfield> and <structfield>apdu.sw2</structfield>
fields, respectively.
</para>
<para>
The function should be called after every APDU transmission, to convert the
card's status code to an OpenSC error code.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

38
doc/api/card/sc_format_apdu.xml
View File

@ -1,38 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scformatapdu">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_format_apdu</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_format_apdu</refname>
<refpurpose>Populate an APDU structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
void sc_format_apdu(struct sc_card *card, sc_apdu_t *apdu,
int cse, int ins, int p1, int p2);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function populates the sc_apdu_t structure
pointed to by <emphasis>apdu</emphasis> on <emphasis>card</emphasis>. It does
not allocate memory. The <emphasis>cse</emphasis>, <emphasis>ins</emphasis>,
<emphasis>p1</emphasis> and <emphasis>p2</emphasis> parameters correspond to
the respective APDU parameters as described in the
ISO 7816 standard.
</para>
</refsect1>
</refentry>

41
doc/api/card/sc_get_challenge.xml
View File

@ -1,41 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scgetchallenge">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_get_challenge</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_get_challenge</refname>
<refpurpose>Request a challenge from a card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_get_challenge(struct sc_card *card, unsigned char *rnd, size_t len);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function requests a challenge (i.e. random bytes) from
<emphasis>card</emphasis>. The returned data will be stored in
<emphasis>rnd</emphasis>, and will be <emphasis>len</emphasis> bytes long.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

48
doc/api/card/sc_get_data.xml
View File

@ -1,48 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scgetdata">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_get_data</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_get_data</refname>
<refpurpose>Get a primitive data object from a card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_get_data(sc_card_t *card, unsigned int tag,
unsigned char *buf, size_t buflen);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function is used to retrieve a primitive data object from
<emphasis>card</emphasis>. It corresponds to the GET DATA command in the
ISO 7816 standard. The data is stored in
<emphasis>buf</emphasis>, which is <emphasis>buflen</emphasis> bytes long.
</para>
<para>
The <emphasis>tag</emphasis> parameter specifies the object to be retrieved.
Refer to the standard for the correct values to use.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

41
doc/api/card/sc_lock.xml
View File

@ -1,41 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="sclock">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_lock</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_lock</refname>
<refpurpose>Lock a card for exclusive use</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_lock(struct sc_card *card);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function locks the card against modification from other threads or processes. The function
may be called several times; a counter will be increased, and the card will be unlocked only
when this counter reaches zero.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 on success, or a negative value in case of error.
</para>
</refsect1>
</refentry>

49
doc/api/card/sc_put_data.xml
View File

@ -1,49 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scputdata">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_put_data</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_put_data</refname>
<refpurpose>Store a primitive data object on a card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_put_data(sc_card_t *card, unsigned int tag,
const unsigned char *buf, size_t len);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function is used to store a primitive data object on
<emphasis>card</emphasis>. It corresponds to the PUT DATA command in the
ISO 7816 standard. The data to be sent to the
card is stored in <emphasis>buf</emphasis>, which is
<emphasis>buflen</emphasis> bytes long.
</para>
<para>
The <emphasis>tag</emphasis> parameter specifies the object to be stored.
Refer to the standard for the correct values to use.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

40
doc/api/card/sc_transmit_apdu.xml
View File

@ -1,40 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="sctransmitapdu">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_transmit_apdu</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_transmit_apdu</refname>
<refpurpose>Transmit an APDU structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_transmit_apdu(struct sc_card *card, sc_apdu_t *apdu);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function transmits the APDU in <emphasis>apdu</emphasis> to
<emphasis>card</emphasis>.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

40
doc/api/card/sc_unlock.xml
View File

@ -1,40 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scunlock">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_unlock</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_unlock</refname>
<refpurpose>Unlock a card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_unlock(struct sc_card *card);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function unlocks <emphasis>card</emphasis>. That is, the lock count is decreased, and the
card unlocked if it reaches zero.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

71
doc/api/card/sc_wait_for_event.xml
View File

@ -1,71 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scwaitforevent">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_wait_for_event</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_wait_for_event</refname>
<refpurpose>Wait for an event on a smart card reader</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_wait_for_event(sc_reader_t *readers[], int slots[], size_t numslots,
unsigned int event_mask,
int *reader, unsigned int *event, int timeout);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function blocks until an event occurs on any of the
readers/slots specified. The <emphasis>readers</emphasis> and <emphasis>slots</emphasis>
fields list the readers and
respective slots to be watched. <emphasis>num_slots</emphasis>
holds the total number of slots passed. The <emphasis>event_mask</emphasis>
parameter specifies the types of events to wait for. This may be a
combination of the following flags:
<variablelist>
<varlistentry>
<term><symbol>SC_EVENT_CARD_REMOVED</symbol></term>
<listitem><para>A card was removed from the reader/slot.</para></listitem>
</varlistentry>
<varlistentry>
<term><symbol>SC_EVENT_CARD_INSERTED</symbol></term>
<listitem><para>A card was inserted into the reader/slot.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
On returning, the <emphasis>reader</emphasis> parameter holds the
reader which generated an event, and <emphasis>event</emphasis> holds
the event flag, as in <emphasis>event_mask</emphasis>.
</para>
<para>
The timeout parameter may be used to specify the maximum amount of
time to wait for an event, in milliseconds. This may be set to -1
to wait forever.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, 1 if a timeout occurred, or a negative
value in case of error.
</para>
</refsect1>
</refentry>

40
doc/api/file/chapter.xml
View File

@ -1,40 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY scfilenew SYSTEM "sc_file_new.xml">
<!ENTITY scfiledup SYSTEM "sc_file_dup.xml">
<!ENTITY sccreatefile SYSTEM "sc_create_file.xml">
<!ENTITY scselectfile SYSTEM "sc_select_file.xml">
<!ENTITY scfilefree SYSTEM "sc_file_free.xml">
<!ENTITY sclistfiles SYSTEM "sc_list_files.xml">
<!ENTITY scdeletefile SYSTEM "sc_delete_file.xml">
<!ENTITY screadbinary SYSTEM "sc_read_binary.xml">
<!ENTITY scupdatebinary SYSTEM "sc_update_binary.xml">
<!ENTITY scwritebinary SYSTEM "sc_write_binary.xml">
<!ENTITY screadrecord SYSTEM "sc_read_record.xml">
<!ENTITY scwriterecord SYSTEM "sc_write_record.xml">
<!ENTITY scupdaterecord SYSTEM "sc_update_record.xml">
<!ENTITY scappendrecord SYSTEM "sc_append_record.xml">
<!ENTITY scdeleterecord SYSTEM "sc_delete_record.xml">
]>
<chapter>
<title>File operations</title>
&scfilenew;
&scfiledup;
&sccreatefile;
&scselectfile;
&scfilefree;
&sclistfiles;
&scdeletefile;
&screadbinary;
&scupdatebinary;
&scwritebinary;
&screadrecord;
&scwriterecord;
&scupdaterecord;
&scappendrecord;
&scdeleterecord;
</chapter>

45
doc/api/file/sc_append_record.xml
View File

@ -1,45 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scappendrecord">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_append_record</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_append_record</refname>
<refpurpose>Append a record to a file</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_append_record(struct sc_card *card,
const unsigned char *buf, size_t buflen,
unsigned long flags);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function appends a record that is <emphasis>buflen</emphasis> bytes long from the buffer
pointed to by <emphasis>buf</emphasis> to a record-structured elementary file (EF) on
<emphasis>card</emphasis>. The function corresponds to the ISO
7816 APPEND RECORD function. Call <link linkend="scselectfile">sc_select_file()</link>
first to select the file to write to.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns the number of bytes written if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

34
doc/api/file/sc_create_file.xml
View File

@ -1,34 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="sccreatefile">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_create_file</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_create_file</refname>
<refpurpose>Create a file object</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_create_file(<link linkend="sccardt">sc_card_t</link> *card, <link linkend="scfilet">sc_file_t</link> *file);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a file on <emphasis>card</emphasis>. The <emphasis>file</emphasis> must
have been created with a call to <link linkend="scfilenew">sc_file_new()</link> beforehand.
</para>
</refsect1>
</refentry>

40
doc/api/file/sc_delete_file.xml
View File

@ -1,40 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scdeletefile">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_delete_file</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_delete_file</refname>
<refpurpose>Delete a file</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_delete_file(struct sc_card *card, const struct sc_path *path);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function deletes a file specified by <emphasis>path</emphasis> on
<emphasis>card</emphasis>.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

42
doc/api/file/sc_delete_record.xml
View File

@ -1,42 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scdeleterecord">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_delete_record</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_delete_record</refname>
<refpurpose>Delete a record from a file</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_delete_record(struct sc_card *card, unsigned int rec_nr);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function deletes a record specified by <emphasis>rec_nr</emphasis> on
<emphasis>card</emphasis>. This is not a standard ISO
7816 operation, and is currently only supported on the
Oberthur smart cards.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

37
doc/api/file/sc_file_dup.xml
View File

@ -1,37 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scfiledup">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_file_dup</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_file_dup</refname>
<refpurpose>Duplicate a file object</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
void sc_file_dup(<link linkend="scfilet">sc_file_t</link> **dest, const <link
linkend="scfilet">sc_file_t</link> *src)
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates a new file object, duplicates all file information from
<emphasis>src</emphasis> into it, and stores it in the pointer pointed to by
<emphasis>dest</emphasis>. This object must be released with <link
linkend="scfilefree">sc_file_free()</link> after use.
</para>
</refsect1>
</refentry>

35
doc/api/file/sc_file_free.xml
View File

@ -1,35 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scfilefree">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_file_free</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_file_free</refname>
<refpurpose>Free file object</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
void sc_file_free(<link linkend="scfilet">sc_file_t</link> *file);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function releases a file object previously allocated by <link
linkend="scselectfile">sc_select_file()</link>.
</para>
</refsect1>
</refentry>

34
doc/api/file/sc_file_new.xml
View File

@ -1,34 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scfilenew">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_file_new</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_file_new</refname>
<refpurpose>Create a file object</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
<link linkend="scfilet">sc_file_t</link> *sc_file_new(void);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates an empty OpenSC file object, which can later be passed to <link
linkend="sccreatefile">sc_create_file()</link>.
</para>
</refsect1>
</refentry>

42
doc/api/file/sc_list_files.xml
View File

@ -1,42 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="sclistfiles">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_list_files</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_list_files</refname>
<refpurpose>List files</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_list_files(struct sc_card *card, unsigned char *buf, size_t buflen);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function lists all files in the currently selected DF, and stores the file IDs as big-endian
16-bit words in <emphasis>buffer</emphasis>, which is <emphasis>buflen</emphasis> bytes long. If
the supplied buffer is too small to hold all file IDs, the listing is silently truncated.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns the number of bytes stored in <emphasis>buffer</emphasis>, or a negative value in case of
error.
</para>
</refsect1>
</refentry>

54
doc/api/file/sc_read_binary.xml
View File

@ -1,54 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="screadbinary">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_read_binary</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_read_binary</refname>
<refpurpose>Read a file</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_read_binary(struct sc_card *card, unsigned int offset,
unsigned char *buf, size_t count,
unsigned long flags);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function reads from a transparent elementary file (EF) on <emphasis>card</emphasis>. It
corresponds to the ISO 7816 READ BINARY function. Call <link
linkend="scselectfile">sc_select_file()</link> first to select the file to read from.
</para>
<para>
The data read from the file is stored in <emphasis>buf</emphasis>, which is
<emphasis>count</emphasis> bytes long.
</para>
<para>
The <emphasis>offset</emphasis> argument specifies the file offset in bytes. The
<emphasis>flags</emphasis> argument is currently not used, and should be set to 0.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
If successful, the number of bytes read is returned. Otherwise, a negative value is
returned.
</para>
</refsect1>
</refentry>

54
doc/api/file/sc_read_record.xml
View File

@ -1,54 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="screadrecord">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_read_record</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_read_record</refname>
<refpurpose>Read a record from a file</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_read_record(struct sc_card *card, unsigned int record,
unsigned char *buf, size_t buflen,
unsigned long flags);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function reads a record-structured elementary file (EF) from <emphasis>card</emphasis>. The
function corresponds to the ISO 7816 READ RECORD function. Call
<link linkend="scselectfile">sc_select_file()</link> first to select the file to read from.
</para>
<para>
<emphasis>record</emphasis> specifies the ID of the record to be read, or, if
<emphasis>flags</emphasis> is set to <symbol>SC_RECORD_BY_REC_NR</symbol>, the record number. If
<emphasis>record</emphasis> is set to zero, the current record will be read.
</para>
<para>
The read data is stored in <emphasis>buf</emphasis>, which is <emphasis>buflen</emphasis> bytes
long.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns the number of bytes read if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

55
doc/api/file/sc_select_file.xml
View File

@ -1,55 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scselectfile">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_select_file</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_select_file</refname>
<refpurpose>Select a file on a smart card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_select_file(<link linkend="sccardt">sc_card_t</link> *card,
const <link linkend="scpatht">sc_path_t</link> *path,
<link linkend="scfilet">sc_file_t</link> **result);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function selects the file specified by <emphasis>path</emphasis>. If
<emphasis>path</emphasis> specifies a file within the currently selected DF, sc_select_file() will
<emphasis>not</emphasis> select the MF first, but interpret the path relative to the current DF.
It does this in order to prevent losing any authorizations previously established with the card
(e.g. by presenting a PIN).
</para>
<para>
If <emphasis>result</emphasis> is not NULL, an <link linkend="scfilet">sc_file_t</link> object is
created, and the pointer to this object is stored in the location pointed to by
<emphasis>result</emphasis>. This handle should later be released using <link
linkend="scfilefree">sc_file_free()</link>.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
If an error occurred, a negative error code is returned. Otherwise, the function will return 0.
</para>
</refsect1>
</refentry>

56
doc/api/file/sc_update_binary.xml
View File

@ -1,56 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scupdatebinary">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_update_binary</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_update_binary</refname>
<refpurpose>Write to an existing file</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_update_binary(struct sc_card *card, unsigned int offset,
const unsigned char *buf, size_t count,
unsigned long flags);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function writes <emphasis>count</emphasis> bytes from the buffer pointed to by
<emphasis>buf</emphasis> to a transparent elementary file (EF) on <emphasis>card</emphasis>. It
corresponds to the ISO 7816 UPDATE BINARY function. Call <link
linkend="scselectfile">sc_select_file()</link> first to select the file to write to.
</para>
<para>
This function can only be used to write to a file region previously written to. For writing to a
newly created file, or a new region of an existing file, use <link
linkend="scwritebinary">sc_write_binary()</link>.
</para>
<para>
The <emphasis>offset</emphasis> argument specifies the file offset in bytes. The
<emphasis>flags</emphasis> argument is currently not used, and should be set to 0.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
If successful, the number of bytes written is returned. Otherwise, a negative value is
returned.
</para>
</refsect1>
</refentry>

56
doc/api/file/sc_update_record.xml
View File

@ -1,56 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scupdaterecord">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_update_record</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_update_record</refname>
<refpurpose>Write a record to an existing file</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_update_record(struct sc_card *card, unsigned int record,
const unsigned char *buf, size_t buflen,
unsigned long flags);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function writes a record that is <emphasis>buflen</emphasis> bytes long from the buffer
pointed to by <emphasis>buf</emphasis> to a record-structured elementary file (EF) on
<emphasis>card</emphasis>. The function corresponds to the ISO
7816 UPDATE RECORD function. Call <link linkend="scselectfile">sc_select_file()</link>
first to select the file to write to.
</para>
<para>
<emphasis>record</emphasis> specifies the ID of the record to be written, or, if
<emphasis>flags</emphasis> is set to <symbol>SC_RECORD_BY_REC_NR</symbol>, the record number. If
<emphasis>record</emphasis> is set to zero, the current record will be read.
</para>
<para>
This function can be used for overwriting existing records only; for appending to
files, see the <link linkend="scappendrecord">sc_append_record()</link> function.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns the number of bytes written if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

56
doc/api/file/sc_write_binary.xml
View File

@ -1,56 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scwritebinary">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_write_binary</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_write_binary</refname>
<refpurpose>Write to a new file</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_write_binary(struct sc_card *card, unsigned int offset,
const unsigned char *buf, size_t count,
unsigned long flags);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function writes <emphasis>count</emphasis> bytes from the buffer pointed to by
<emphasis>buf</emphasis> to a transparent elementary file (EF) on <emphasis>card</emphasis>. It
corresponds to the ISO 7816 WRITE BINARY function. Call <link
linkend="scselectfile">sc_select_file()</link> first to select the file to write to.
</para>
<para>
This function is used to write to a newly created file, or to a a previously unused portion of a
file. For updating an existing file, use the <link
linkend="scupdatebinary">sc_update_binary()</link> function.
</para>
<para>
The <emphasis>offset</emphasis> argument specifies the file offset in bytes. The
<emphasis>flags</emphasis> argument is currently not used, and should be set to 0.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
If successful, the number of bytes written is returned. Otherwise, a negative value is
returned.
</para>
</refsect1>
</refentry>

57
doc/api/file/sc_write_record.xml
View File

@ -1,57 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scwriterecord">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_write_record</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_write_record</refname>
<refpurpose>Write a record to a file</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_write_record(struct sc_card *card, unsigned int record,
const unsigned char *buf, size_t buflen,
unsigned long flags);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function writes a record that is <emphasis>buflen</emphasis> bytes long from the buffer
pointed to by <emphasis>buf</emphasis> to a record-structured elementary file (EF) on
<emphasis>card</emphasis>. The function corresponds to the ISO
7816 WRITE RECORD function. Call <link linkend="scselectfile">sc_select_file()</link>
first to select the file to write to.
</para>
<para>
<emphasis>record</emphasis> specifies the ID of the record to be written, or, if
<emphasis>flags</emphasis> is set to <symbol>SC_RECORD_BY_REC_NR</symbol>, the record number. If
<emphasis>record</emphasis> is set to zero, the current record will be read.
</para>
<para>
This function is used for newly created files only; for updating or appending to
existing files, see the <link linkend="scupdaterecord">sc_update_record()</link> and <link
linkend="scappendrecord">sc_append_record()</link> functions, respectively.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns the number of bytes written if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

26
doc/api/init/chapter.xml
View File

@ -1,26 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY scestablishcontext SYSTEM "sc_establish_context.xml">
<!ENTITY screleasecontext SYSTEM "sc_release_context.xml">
<!ENTITY scgetcachedir SYSTEM "sc_get_cache_dir.xml">
<!ENTITY scmakecachedir SYSTEM "sc_make_cache_dir.xml">
<!ENTITY scconnectcard SYSTEM "sc_connect_card.xml">
<!ENTITY scdisconnectcard SYSTEM "sc_disconnect_card.xml">
<!ENTITY scdetectcardpresence SYSTEM "sc_detect_card_presence.xml">
<!ENTITY sccardvalid SYSTEM "sc_card_valid.xml">
<!ENTITY scsetcarddriver SYSTEM "sc_set_card_driver.xml">
]>
<chapter>
<title>Initialization</title>
&scestablishcontext;
&screleasecontext;
&scgetcachedir;
&scmakecachedir;
&scconnectcard;
&scdisconnectcard;
&scdetectcardpresence;
&sccardvalid;
&scsetcarddriver;
</chapter>

41
doc/api/init/sc_card_valid.xml
View File

@ -1,41 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="sccardvalid">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_card_valid</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_card_valid</refname>
<refpurpose>Check if a card is valid</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_card_valid(const <link linkend="sccardt">sc_card_t</link> *card);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Checks if <emphasis>card</emphasis> is a valid <link linkend="sccardt">sc_card_t</link> object.
Mostly used internally by the library.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 1 if <emphasis>card</emphasis> is a valid object.
</para>
</refsect1>
</refentry>

50
doc/api/init/sc_connect_card.xml
View File

@ -1,50 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scconnectcard">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_connect_card</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_connect_card</refname>
<refpurpose>Connect to smart card in reader</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_connect_card(sc_reader_t *reader, int slot, <link linkend="sccardt">sc_card_t</link> **card);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function connects to a card in a reader, resets the card and retrieves the ATR (Answer To
Reset). Based on the ATR, it tries to auto-detect which card driver to use.
</para>
<para>
The <emphasis>slot</emphasis> parameter identifies the card reader's slot. Slots are numbered
consecutively, starting at 0.
</para>
<para>
If OpenSC was able to connect to the card, a pointer to the sc_card_t object is stored in the
location pointer to by the <emphasis>card</emphasis> parameter. The card handle should be
released with <link linkend="scdisconnectcard">sc_disconnect_card</link> when no longer in use.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>Returns 0 if successful, or a negative value in case of error.</para>
</refsect1>
</refentry>

43
doc/api/init/sc_detect_card_presence.xml
View File

@ -1,43 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scdetectcardpresence">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_detect_card_presence</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_detect_card_presence</refname>
<refpurpose>Detect presence of smart card in a reader</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_detect_card_presence(sc_reader_t *reader, int slot_id);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function checks whether <emphasis>reader</emphasis> has a card present in
<emphasis>slot_id</emphasis>.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
If an error occurred, the return value is a a negative OpenSC error code. If no card is present, 0
is returned. Otherwise, a positive value is returned, which is a combination of flags. The flag
SC_SLOT_CARD_PRESENT is always set. In addition, if the card was exchanged, the
SC_SLOT_CARD_CHANGED flag is set.
</para>
</refsect1>
</refentry>

47
doc/api/init/sc_disconnect_card.xml
View File

@ -1,47 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scdisconnectcard">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_disconnect_card</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_disconnect_card</refname>
<refpurpose>Disconnect from a smart card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_disconnect_card(<link linkend="sccardt">sc_card_t</link> *card, int action);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function disconnects from <emphasis>card</emphasis>, and frees the card structure. Any locks made
by the application must be released before calling this function.
</para>
<para>
The <emphasis>action</emphasis> parameter is not used at the moment and should be set to 0.
</para>
<para>
The card is not reset nor powered down after the operation.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>Returns 0 if successful, or a negative value in case of error.</para>
</refsect1>
</refentry>

85
doc/api/init/sc_establish_context.xml
View File

@ -1,85 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scestablishcontext">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_establish_context</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_establish_context</refname>
<refpurpose>Establish an OpenSC context</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_establish_context(sc_context_t **ctx,
const char *appname);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function establishes an OpenSC context. This context is required
in all subsequent calls to OpenSC functions.
</para>
<para>
<emphasis>ctx</emphasis> is a pointer to a pointer that will receive the allocated context.
</para>
<para>
<emphasis>appname</emphasis> is a string that identifies the application. This string will
be used to apply application-specific settings from the
opensc.conf configuration file. If NULL is passed, only the
settings specified in the default section apply; otherwise, settings from the section
identified by <emphasis>appname</emphasis> will be applied as well.
</para>
<para>
The <structname>sc_context</structname> structure contains the following members:
</para>
<para>
<programlisting>
#define SC_MAX_READERS 16
typedef struct sc_context {
struct sc_reader *reader[SC_MAX_READERS];
int reader_count;
} sc_context_t;
</programlisting>
</para>
<para>
The <emphasis>reader_count</emphasis> field contains the number of readers found. Information on
the individual card readers is stored in <emphasis>sc_reader</emphasis> objects, defined as
follows:
</para>
<para>
<programlisting>
typedef struct sc_reader {
char *name;
int slot_count;
}; sc_reader_t;
</programlisting>
</para>
<para>In this structure, <emphasis>name</emphasis> contains a printable name of the reader, and
<emphasis>slot_count</emphasis> has the number of slots supported by this device.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>Returns 0 if successful, or a negative value in case of error.</para>
</refsect1>
</refentry>

40
doc/api/init/sc_get_cache_dir.xml
View File

@ -1,40 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scgetcachedir">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_get_cache_dir</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_get_cache_dir</refname>
<refpurpose>Get the OpenSC cache directory</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_get_cache_dir(struct sc_context *ctx, char *buf, size_t bufsize);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function stores the OpenSC cache directory for the current user in the buffer pointed to by
<emphasis>buf</emphasis>, which is <emphasis>bufsize</emphasis> bytes long.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

41
doc/api/init/sc_make_cache_dir.xml
View File

@ -1,41 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scmakecachedir">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_make_cache_dir</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_make_cache_dir</refname>
<refpurpose>Create the OpenSC cache directory</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_make_cache_dir(struct sc_context *ctx);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function creates the OpenSC cache directory for the current user, and any directories
leading up to it.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

41
doc/api/init/sc_release_context.xml
View File

@ -1,41 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="screleasecontext">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_release_context</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_release_context</refname>
<refpurpose>Release an OpenSC context</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_release_context(sc_context_t *ctx);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function releases OpenSC context <emphasis>ctx</emphasis> previously obtained through a call
to <link linkend="scestablishcontext">sc_establish_context()</link>. No further calls to OpenSC
using this context are possible after this.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>This function always return 0, indicating success.</para>
</refsect1>
</refentry>

66
doc/api/init/sc_set_card_driver.xml
View File

@ -1,66 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scsetcarddriver">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_set_card_driver</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_set_card_driver</refname>
<refpurpose>Force the use of a specified smart card driver</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_set_card_driver(struct sc_context *ctx, const char *short_name);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function forces the use of a a specific card driver to be used in context
<emphasis>ctx</emphasis>. The name of the driver is specified in <emphasis>short_name</emphasis>.
Possible options are:
<simplelist type="vert" columns="1">
<member>etoken</member>
<member>flex</member>
<member>cyberflex</member>
<member>gpk</member>
<member>miocos</member>
<member>mcrd</member>
<member>setcos</member>
<member>starcos</member>
<member>tcos</member>
<member>openpgp</member>
<member>jcop</member>
<member>oberthur</member>
<member>belpic</member>
<member>emv</member>
</simplelist>
</para>
<para>
This function only needs to be called if OpenSC fails to auto-detect your card. If used, it
should be called immediately after establishing a new context with <link
linkend="scestablishcontext">sc_establish_context()</link>, but before doing anything else with
the context.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
If an error occurred, a negative value is returned indicating the error. Otherwise, 0 is
returned.
</para>
</refsect1>
</refentry>

11
doc/api/misc/chapter.xml
View File

@ -1,11 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
]>
<chapter>
<title>Unsorted functions</title>
</chapter>

23
doc/api/types/chapter.xml
View File

@ -1,23 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY scfilet SYSTEM "sc_file_t.xml">
<!ENTITY scpatht SYSTEM "sc_path_t.xml">
<!ENTITY sccardt SYSTEM "sc_card_t.xml">
<!ENTITY scappinfot SYSTEM "sc_app_info_t.xml">
<!ENTITY scasn1entry SYSTEM "sc_asn1_entry.xml">
]>
<chapter>
<title>Data types</title>
<para>
This chapter defines the structures OpenSC uses to store information. Fields internal to
OpenSC are not shown.
</para>
&sccardt;
&scpatht;
&scfilet;
&scappinfot;
&scasn1entry;
</chapter>

97
doc/api/types/sc_app_info_t.xml
View File

@ -1,97 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scappinfot">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_app_info_t</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_app_info_t</refname>
<refpurpose>OpenSC application structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
#define SC_MAX_AID_SIZE 16
typedef struct sc_app_info {
unsigned char aid[SC_MAX_AID_SIZE];
size_t aid_len;
char *label;
sc_path_t path;
unsigned char *ddo;
size_t ddo_len;
const char *desc;
int rec_nr;
} sc_app_info_t;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This structure describes a smart card application. It contains the following
members:
<variablelist>
<varlistentry>
<term><structfield>aid</structfield></term>
<listitem><para>The applications's AID. An AID uniquely identifies an
application, and consists of an RID (a 5-byte "Registered Application
Provider Identifier") and a PIX, which identifies an application by that
provider. For example, the RID for PKCS#15 consists of the bytes A0 00 00
00 63, and the PIX is the string "PKCS-15". Thus, the AID of a PKCS#15
application on a smart card is A0 00 00 00 63 50 4B 43 53 2D 31.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structfield>aid_len</structfield></term>
<listitem><para>The length of the AID in bytes.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>label</structfield></term>
<listitem><para>A UTF-8 string describing the application.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>path</structfield></term>
<listitem><para>The application's full path on the card, starting at the MF.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>ddo</structfield></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>ddo_len</structfield></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>desc</structfield></term>
<listitem><para>A description of the application, if available.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>rec_nr</structfield></term>
<listitem><para>If the EF(DIR) file is record-structured, this has the
record number in which this application is stored. Otherwise, this is -1.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry>

72
doc/api/types/sc_asn1_entry.xml
View File

@ -1,72 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scasn1entry">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_asn1_entry</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_asn1_entry</refname>
<refpurpose>OpenSC ASN1 entry structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
struct sc_asn1_entry {
const char *name;
unsigned int type;
unsigned int tag;
unsigned int flags;
void *parm;
void *arg;
};
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This structure describes an ASN1 entry structure. It contains the following
members:
<variablelist>
<varlistentry>
<term><structfield>name</structfield></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>type</structfield></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>tag</structfield></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>flags</structfield></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>parm</structfield></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>arg</structfield></term>
<listitem><para></para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry>

73
doc/api/types/sc_card_t.xml
View File

@ -1,73 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="sccardt">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_card_t</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_card_t</refname>
<refpurpose>OpenSC card structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
#define SC_MAX_ATR_SIZE 33
#define SC_MAX_CARD_APPS 8
typedef struct sc_card {
struct sc_context *ctx;
struct sc_reader *reader;
struct sc_slot_info *slot;
struct sc_app_info *app[SC_MAX_CARD_APPS];
unsigned char atr[SC_MAX_ATR_SIZE];
size_t atr_len;
} sc_card_t;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This structure describes a smart card object. It contains the following
members:
<variablelist>
<varlistentry>
<term><structfield>ctx</structfield></term>
<listitem><para>The context this card is associated with.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>reader</structfield></term>
<listitem><para>The reader this card is inserted into.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>slot</structfield></term>
<listitem><para>The slot on the reader this card is inserted into.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>atr</structfield></term>
<listitem><para>The ATR (Answer To Reset) of the card.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>atr_len</structfield></term>
<listitem><para>The length of the <structfield>atr</structfield> field</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry>

98
doc/api/types/sc_file_t.xml
View File

@ -1,98 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scfilet">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_file_t</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_file_t</refname>
<refpurpose>OpenSC file structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
typedef struct sc_file {
struct sc_path path;
int type, ef_structure;
size_t size;
int id;
/* record structured files only */
int record_length;
int record_count;
} sc_file_t;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This structure describes a file object on a smart card. It contains the following members:
<variablelist>
<varlistentry>
<term><structfield>path</structfield></term>
<listitem><para>This is full the path to the file, starting at the MF.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>type</structfield></term>
<listitem><para>This is the file type. It can be one of <symbol>SC_FILE_TYPE_DF</symbol>,
<symbol>SC_FILE_TYPE_WORKING_EF</symbol>, or <symbol>SC_FILE_TYPE_INTERNAL_EF</symbol>.
The latter is used by some cards only, and you normally shouldn't have to deal with these
files.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>ef_structure</structfield></term>
<listitem><para>For elementary files (EFs), this field describes the file's structure.
It can be one of:
<simplelist type="vert" columns="1">
<member>SC_FILE_EF_TRANSPARENT</member>
<member>SC_FILE_EF_LINEAR_FIXED</member>
<member>SC_FILE_EF_LINEAR_FIXED_TLV</member>
<member>SC_FILE_EF_LINEAR_VARIABLE</member>
<member>SC_FILE_EF_LINEAR_VARIABLE_TLV</member>
<member>SC_FILE_EF_CYCLIC</member>
<member>SC_FILE_EF_CYCLIC_TLV</member>
<member>SC_FILE_EF_UNKNOWN</member>
</simplelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>size</structfield></term>
<listitem><para>gives the file's size in bytes.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>id</structfield></term>
<listitem><para>gives the file's ID, as a 16-bit number.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>record_count, record_length</structfield></term>
<listitem><para>For record structured files, <structfield>record_sount</structfield>
specifies the number of records in the file. For files with fixed length records,
<structfield>record_length</structfield> contains the record length.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry>

83
doc/api/types/sc_path_t.xml
View File

@ -1,83 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scpatht">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_path_t</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_file_t</refname>
<refpurpose>OpenSC path structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
#define SC_MAX_PATH_SIZE 16
typedef struct sc_path {
unsigned char value[SC_MAX_PATH_SIZE];
size_t len;
int index;
int count;
int type;
} sc_path_t;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This structure describes a path object on a smart card. It contains the following
members:
<variablelist>
<varlistentry>
<term><structfield>value</structfield></term>
<listitem><para>This is the full path to the file, starting at the MF.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>length</structfield></term>
<listitem><para>The length of the path.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>index</structfield></term>
<listitem><para>Used only in PKCS15, this indicates the offset into the file.
</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>count</structfield></term>
<listitem><para>Used only in PKCS15, this indicates the number of octets in the
record, starting from <structfield>index</structfield> above.</para></listitem>
</varlistentry>
<varlistentry>
<term><structfield>type</structfield></term>
<listitem><para>The path type. This can be one of:
<simplelist type="vert" columns="1">
<member>SC_PATH_TYPE_FILE_ID</member>
<member>SC_PATH_TYPE_DF_NAME</member>
<member>SC_PATH_TYPE_PATH</member>
<member>SC_PATH_TYPE_PATH_PROT</member>
</simplelist>
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry>

21
doc/api/util/chapter.xml
View File

@ -1,21 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY scbase64encode SYSTEM "sc_base64_encode.xml">
<!ENTITY scbase64decode SYSTEM "sc_base64_decode.xml">
<!ENTITY scdercopy SYSTEM "sc_der_copy.xml">
<!ENTITY scderclear SYSTEM "sc_der_clear.xml">
<!ENTITY scstrerror SYSTEM "sc_strerror.xml">
]>
<chapter>
<title>Miscellaneous utility functions</title>
&scstrerror;
&scbase64encode;
&scbase64decode;
&scdercopy;
&scderclear;
</chapter>

42
doc/api/util/sc_base64_decode.xml
View File

@ -1,42 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scbase64decode">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_base64_decode</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_base64_decode</refname>
<refpurpose>Decode a base64 stream</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_base64_decode(const char *inbuf,
unsigned char *outbuf, size_t outlen);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function decodes the base64 stream in <emphasis>inbuf</emphasis>, which is NULL-terminated,
to the buffer pointed to by <emphasis>outbuf</emphasis> (which is <emphasis>outlen</emphasis>
bytes long);
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

49
doc/api/util/sc_base64_encode.xml
View File

@ -1,49 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scbase64encode">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_base64_encode</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_base64_encode</refname>
<refpurpose>Encode a stream to base64</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
int sc_base64_encode(const unsigned char *inbuf, size_t inlen,
unsigned char *outbuf, size_t outlen,
size_t linelength);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function encodes the buffer pointed to by <emphasis>inbuf</emphasis> of size
<emphasis>inlen</emphasis> as base64, and stores the result in <emphasis>outbuf</emphasis>, which
is <emphasis>outlen</emphasis> bytes long. A linefeed (\n) will be inserted every
<emphasis>linelength</emphasis> bytes in the output buffer.
</para>
<para>
You must ensure <emphasis>outbuf</emphasis> has enough space to store the base64-encoded version
of <emphasis>inbuf</emphasis>.
</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
Returns 0 if successful, or a negative value in case of error.
</para>
</refsect1>
</refentry>

32
doc/api/util/sc_der_clear.xml
View File

@ -1,32 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scderclear">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_der_clear</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_der_clear</refname>
<refpurpose>Clear DER structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
void sc_der_clear(sc_pkcs15_der_t *der);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function clears the OpenSC DER structure pointed to by <emphasis>der</emphasis>.
</para>
</refsect1>
</refentry>

33
doc/api/util/sc_der_copy.xml
View File

@ -1,33 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scdercopy">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_der_copy</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_der_copy</refname>
<refpurpose>Copy a DER structure</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
void sc_der_copy(sc_pkcs15_der_t *dst, const sc_pkcs15_der_t *src);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function copies the OpenSC DER structure pointed to by <emphasis>src</emphasis> to
<emphasis>dst</emphasis>, which must point to enough space to hold this structure.
</para>
</refsect1>
</refentry>

33
doc/api/util/sc_strerror.xml
View File

@ -1,33 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="scstrerror">
<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
<refmeta>
<refentrytitle>sc_strerror</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>sc_strerror</refname>
<refpurpose>Return string describing error code</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<programlisting>
#include &lt;opensc.h&gt;
const char *sc_strerror(int error);
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This function returns a string describing <emphasis>error</emphasis>. It may
be used with a negative errorcode returned by any OpenSC function call.
</para>
</refsect1>
</refentry>