diff --git a/doc/advanced-topics.xml b/doc/advanced-topics.xml new file mode 100644 index 00000000..bc674573 --- /dev/null +++ b/doc/advanced-topics.xml @@ -0,0 +1,115 @@ + + + + Advanced Topics + + + Device and print compatibility + + + Moving off generic conceptual ideas and onto libfprint-specific + implementation details, here are some introductory notes regarding how + libfprint copes with compatibility of fingerprints. + + + + libfprint deals with a whole variety of different fingerprint readers and + the design includes considerations of compatibility and interoperability + between multiple devices. Your application should also be prepared to + work with more than one type of fingerprint reader and should consider that + enrolled fingerprint X may not be compatible with the device the user has + plugged in today. + + + + libfprint implements the principle that fingerprints from different devices + are not necessarily compatible. For example, different devices may see + significantly different areas of fingerprint surface, and comparing images + between the devices would be unreliable. Also, devices can stretch and + distort images in different ways. + + + + libfprint also implements the principle that in some cases, fingerprints + are compatible between different devices. If you go and buy two + identical fingerprint readers, it seems logical that you should be able + to enroll on one and verify on another without problems. + + + + libfprint takes a fairly simplistic approach to these issues. Internally, + fingerprint hardware is driven by individual drivers. libfprint enforces + that a fingerprint that came from a device backed by driver X is never + compared to a fingerprint that came from a device backed by driver Y. + + + + Additionally, libfprint is designed for the situation where a single driver + may support a range of devices which differ in imaging or scanning + properties. For example, a driver may support two ranges of devices which + even though are programmed over the same interface, one device sees + substantially less of the finger flesh, therefore images from the two + device types should be incompatible despite being from the same driver. To + implement this, each driver assigns a device type to each device + that it detects based on its imaging characteristics. libfprint ensures that + two prints being compared have the same device type. + + + + In summary, libfprint represents fingerprints in several internal structures + and each representation will offer you a way of determining the + \ref driver_id "driver ID" and \ref devtype "devtype" of the print in + question. Prints are only compatible if the driver ID and devtypes + match. libfprint does offer you some "is this print compatible?" helper + functions, so you don't have to worry about these details too much. + + + + + Driver IDs + + + Each driver is assigned a unique ID by the project maintainer. These + assignments are + + documented on the wiki and will never change. + + + + The only reason you may be interested in retrieving the driver ID for a + driver is for the purpose of checking if some print data is compatible + with a device. libfprint uses the driver ID as one way of checking that + the print you are trying to verify is compatible with the device in + question - it ensures that enrollment data from one driver is never fed to + another. Note that libfprint does provide you with helper functions to + determine whether a print is compatible with a device, so under most + circumstances, you don't have to worry about driver IDs at all. + + + + + Device types + + + Internally, the \ref drv "driver" behind a device assigns a 32-bit + devtype identifier to the device. This cannot be used as a unique + ID for a specific device as many devices under the same range may share + the same devtype. The devtype may even be 0 in all cases. + + + + The only reason you may be interested in retrieving the devtype for a + device is for the purpose of checking if some print data is compatible + with a device. libfprint uses the devtype as one way of checking that the + print you are verifying is compatible with the device in question - the + devtypes must be equal. This effectively allows drivers to support more + than one type of device where the data from each one is not compatible with + the other. Note that libfprint does provide you with helper functions to + determine whether a print is compatible with a device, so under most + circumstances, you don't have to worry about devtypes at all. + + + + diff --git a/doc/doxygen.cfg.in b/doc/doxygen.cfg.in deleted file mode 100644 index da7bf494..00000000 --- a/doc/doxygen.cfg.in +++ /dev/null @@ -1,1294 +0,0 @@ -# Doxyfile 1.5.3 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project -# -# All text after a hash (#) is considered a comment and will be ignored -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# This tag specifies the encoding used for all characters in the config file that -# follow. The default is UTF-8 which is also the encoding used for all text before -# the first occurrence of this tag. Doxygen uses libiconv (or the iconv built into -# libc) for the transcoding. See http://www.gnu.org/software/libiconv for the list of -# possible encodings. - -DOXYFILE_ENCODING = UTF-8 - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. - -PROJECT_NAME = libfprint - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -PROJECT_NUMBER = - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, -# Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hungarian, -# Italian, Japanese, Japanese-en (Japanese with English messages), Korean, -# Korean-en, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, -# Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian. - -OUTPUT_LANGUAGE = English - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = NO - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = NO - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like regular Qt-style comments -# (thus requiring an explicit @brief command for a brief description.) - -JAVADOC_AUTOBRIEF = YES - -# If the QT_AUTOBRIEF tag is set to YES then Doxygen will -# interpret the first line (until the first dot) of a Qt-style -# comment as the brief description. If set to NO, the comments -# will behave just like regular Qt-style comments (thus requiring -# an explicit \brief command for a brief description.) - -QT_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the DETAILS_AT_TOP tag is set to YES then Doxygen -# will output the detailed description near the top, like JavaDoc. -# If set to NO, the detailed description appears after the member -# documentation. - -DETAILS_AT_TOP = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 4 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = YES - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for Java. -# For instance, namespaces will be presented as packages, qualified scopes -# will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want to -# include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. - -BUILTIN_STL_SUPPORT = NO - -# If you use Microsoft's C++/CLI language, you should set this option to YES to -# enable parsing support. - -CPP_CLI_SUPPORT = NO - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = NO - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = YES - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = YES - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If this flag is set to YES, the members of anonymous namespaces will be extracted -# and appear in the documentation as a namespace called 'anonymous_namespace{file}', -# where file will be replaced with the base name of the file that contains the anonymous -# namespace. By default anonymous namespace are hidden. - -EXTRACT_ANON_NSPACES = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = YES - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = NO - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = YES - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = NO - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is NO. - -SHOW_DIRECTORIES = NO - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from the -# version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the program writes to standard output -# is used as the file version. See the manual for examples. - -FILE_VERSION_FILTER = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = YES - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = YES - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -WARN_NO_PARAMDOC = NO - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = "$file:$line: $text" - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = "@SRCDIR@" - -# This tag can be used to specify the character encoding of the source files that -# doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default -# input encoding. Doxygen uses libiconv (or the iconv built into libc) for the transcoding. -# See http://www.gnu.org/software/libiconv for the list of possible encodings. - -INPUT_ENCODING = UTF-8 - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py - -FILE_PATTERNS = - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = NO - -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. - -EXCLUDE = ../libfprint/fp_internal.h - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names -# (namespaces, classes, functions, etc.) that should be excluded from the output. -# The symbol name can be a fully qualified name, a word, or if the wildcard * is used, -# a substring. Examples: ANamespace, AClass, AClass::ANamespace, ANamespace::*Test - -EXCLUDE_SYMBOLS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = NO - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. If you have enabled CALL_GRAPH or CALLER_GRAPH -# then you must also enable this option. If you don't then doxygen will produce -# a warning and turn it on anyway - -SOURCE_BROWSER = NO - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = YES - -# If the REFERENCED_BY_RELATION tag is set to YES (the default) -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = YES - -# If the REFERENCES_RELATION tag is set to YES (the default) -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = YES - -# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) -# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from -# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will -# link to the source code. Otherwise they will link to the documentstion. - -REFERENCES_LINK_SOURCE = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = YES - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 5 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = "@BUILDDIR@/html" - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. - -HTML_HEADER = - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = - -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = NO - -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. For this to work a browser that supports -# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox -# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). - -HTML_DYNAMIC_SECTIONS = YES - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. - -DISABLE_INDEX = NO - -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - -# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be -# generated containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. - -GENERATE_TREEVIEW = NO - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = latex - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. - -LATEX_CMD_NAME = latex - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = makeindex - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = a4wide - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = NO - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = NO - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = NO - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = rtf - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = man - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = .3 - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = NO - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = YES - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_DEFINED tags. - -EXPAND_ONLY_PREDEF = YES - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -PREDEFINED = API_EXPORTED= - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse -# the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = NO - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = /usr/bin/perl - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more -# powerful graphs. - -CLASS_DIAGRAMS = YES - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see http://www.mcternan.me.uk/mscgen/) to -# produce the chart and insert it in the documentation. The MSCGEN_PATH tag allows you to -# specify the directory where the mscgen tool resides. If left empty the tool is assumed to -# be found in the default search path. - -MSCGEN_PATH = - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = YES - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = NO - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = YES - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = YES - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -GROUP_GRAPHS = YES - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = NO - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = NO - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH, SOURCE_BROWSER and HAVE_DOT tags are set to YES then doxygen will -# generate a call dependency graph for every global function or class method. -# Note that enabling this option will significantly increase the time of a run. -# So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. - -CALL_GRAPH = NO - -# If the CALLER_GRAPH, SOURCE_BROWSER and HAVE_DOT tags are set to YES then doxygen will -# generate a caller dependency graph for every global function or class method. -# Note that enabling this option will significantly increase the time of a run. -# So in most cases it will be better to enable caller graphs for selected -# functions only using the \callergraph command. - -CALLER_GRAPH = NO - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. - -DOT_IMAGE_FORMAT = png - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The MAX_DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of -# nodes that will be shown in the graph. If the number of nodes in a graph -# becomes larger than this value, doxygen will truncate the graph, which is -# visualized by representing a node as a red box. Note that doxygen if the number -# of direct children of the root node in a graph is already larger than -# MAX_DOT_GRAPH_NOTES then the graph will not be shown at all. Also note -# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. - -DOT_GRAPH_MAX_NODES = 50 - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that the size of a graph can be further restricted by -# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, which results in a white background. -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). - -DOT_TRANSPARENT = NO - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. - -DOT_MULTI_TARGETS = NO - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- - -# The SEARCHENGINE tag specifies whether or not a search engine should be -# used. If set to NO the values of all tags below this one will be ignored. - -SEARCHENGINE = NO diff --git a/doc/getting-started.xml b/doc/getting-started.xml new file mode 100644 index 00000000..5c2d2080 --- /dev/null +++ b/doc/getting-started.xml @@ -0,0 +1,30 @@ + + + + Getting Started + + + libfprint includes several simple functional examples under the examples/ + directory in the libfprint source distribution. Those are good starting + points. + + + + Usually the first thing you want to do is determine which fingerprint + devices are present. This is done through \ref dscv_dev "device discovery". + + + + Once you have found a device you would like to operate, you should open it. + Refer to \ref dev "device operations". This section also details enrollment, + image capture, and verification. + + + + That should be enough to get you started, but do remember there are + documentation pages on other aspects of libfprint's API (see the modules + page). + + diff --git a/doc/intro.xml b/doc/intro.xml new file mode 100644 index 00000000..cfd91008 --- /dev/null +++ b/doc/intro.xml @@ -0,0 +1,106 @@ + + + + Introduction + + + libfprint is an open source library to provide access to fingerprint + scanning devices. For more info, see the + libfprint project homepage. + + + + This documentation is aimed at application developers who wish to integrate + fingerprint-related functionality into their software. libfprint has been + designed so that you only have to do this once - by integrating your + software with libfprint, you'll be supporting all the fingerprint readers + that we have got our hands on. As such, the API is rather general (and + therefore hopefully easy to comprehend!), and does its best to hide the + technical details that required to operate the hardware. + + + + This documentation is not aimed at developers wishing to develop and + contribute fingerprint device drivers to libfprint. + + + + Feedback on this API and its associated documentation is appreciated. Was + anything unclear? Does anything seem unreasonably complicated? Is anything + missing? Let us know on the + mailing list. + + + + Enrollment + + + Before you dive into the API, it's worth introducing a couple of concepts. + + + + The process of enrolling a finger is where you effectively scan your + finger for the purposes of teaching the system what your finger looks like. + This means that you scan your fingerprint, then the system processes it and + stores some data about your fingerprint to refer to later. + + + + + Verification + + + Verification is what most people think of when they think about fingerprint + scanning. The process of verification is effectively performing a fresh + fingerprint scan, and then comparing that scan to a finger that was + previously enrolled. + + + + As an example scenario, verification can be used to implement what people + would picture as fingerprint login (i.e. fingerprint replaces password). + For example: + + + + I enroll my fingerprint through some software that trusts I am who I say + I am. This is a prerequisite before I can perform fingerprint-based + login for my account. + + + Some time later, I want to login to my computer. I enter my username, + but instead of prompting me for a password, it asks me to scan my finger. + I scan my finger. + + + The system compares the finger I just scanned to the one that was + enrolled earlier. If the system decides that the fingerprints match, + I am successfully logged in. Otherwise, the system informs me that I am + not authorised to login as that user. + + + + + + Identification + + + Identification is the process of comparing a freshly scanned fingerprint + to a collection of previously enrolled fingerprints. For example, + imagine there are 100 people in an organisation, and they all have enrolled + their fingerprints. One user walks up to a fingerprint scanner and scans + their finger. With no other knowledge of who that user might be, + the system examines their fingerprint, looks in the database, and determines + that the user is user number #61. + + + + In other words, verification might be seen as a one-to-one fingerprint + comparison where you know the identity of the user that you wish to + authenticate, whereas identification is a one-to-many comparison where you + do not know the identity of the user that you wish to authenticate. + + + diff --git a/doc/libfprint-docs.xml b/doc/libfprint-docs.xml new file mode 100644 index 00000000..8a0ff38b --- /dev/null +++ b/doc/libfprint-docs.xml @@ -0,0 +1,53 @@ + + +]> + + + libfprint Reference Manual + + This document is the API reference for the libfprint library. + + The latest version of libfprint, as well as the latest version of + this API reference, is available online. + + + + + + Library Overview + + + + + + + API Documentation + + + + + + + + + + + + + + API Index + + + + Index of deprecated API + + + diff --git a/doc/libfprint-sections.txt b/doc/libfprint-sections.txt new file mode 100644 index 00000000..fbf13e58 --- /dev/null +++ b/doc/libfprint-sections.txt @@ -0,0 +1,127 @@ +fprint.h + +
+events +Initialisation and events handling +fp_set_debug +fp_init +fp_exit +fp_pollfd +fp_handle_events_timeout +fp_handle_events +fp_get_next_timeout +fp_get_pollfds +fp_set_pollfd_notifiers +
+ +
+discovery +Device discovery +fp_dscv_dev +fp_discover_devs +fp_dscv_devs_free +fp_dscv_dev_get_driver +fp_dscv_dev_get_devtype +fp_dscv_dev_supports_print_data +fp_dscv_dev_supports_dscv_print +fp_dscv_dev_for_print_data +fp_dscv_dev_for_dscv_print +
+ +
+drv +fp_driver +fp_driver_get_name +fp_driver_get_full_name +fp_driver_get_driver_id +fp_driver_get_scan_type +
+ +
+dev +fp_dev +fp_scan_type +fp_capture_result +fp_enroll_result +fp_verify_result + +fp_dev_get_driver +fp_dev_get_nr_enroll_stages +fp_dev_get_devtype +fp_dev_supports_print_data +fp_dev_supports_imaging +fp_dev_supports_identification +fp_dev_supports_dscv_print +fp_dev_get_img_width +fp_dev_get_img_height + +fp_dev_open +fp_async_dev_open + +fp_dev_close +fp_async_dev_close + +fp_enroll_finger +fp_enroll_finger_img +fp_async_enroll_start +fp_async_enroll_stop + +fp_verify_finger +fp_verify_finger_img +fp_async_verify_start +fp_async_verify_stop + +fp_identify_finger +fp_identify_finger_img +fp_async_identify_start +fp_async_identify_stop + +fp_dev_img_capture +fp_async_capture_start +fp_async_capture_stop +
+ +
+print_data +fp_finger +fp_print_data +fp_print_data +fp_print_data_get_data +fp_print_data_from_data +fp_print_data_save +fp_print_data_load +fp_print_data_delete +fp_print_data_from_dscv_print +fp_print_data_free +fp_print_data_get_driver_id +fp_print_data_get_devtype +
+ +
+dscv_print +fp_dscv_print +fp_discover_prints +fp_dscv_prints_free +fp_dscv_print_get_driver_id +fp_dscv_print_get_devtype +fp_dscv_print_get_finger +fp_dscv_print_delete +
+ +
+img +fp_img +fp_minutia +fp_img_free +fp_img_get_height +fp_img_get_width +fp_img_get_data +fp_img_save_to_file +fp_img_standardize +fp_img_binarize +fp_img_get_minutiae +
+ +
+poll +
diff --git a/doc/meson.build b/doc/meson.build index 717efac7..48358c8e 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -1,17 +1,67 @@ -cdata = configuration_data() -cdata.set('SRCDIR', join_paths(meson.source_root(), 'libfprint')) -cdata.set('BUILDDIR', join_paths(meson.build_root(), 'doc')) +subdir('xml') -cfg = configure_file(input: 'doxygen.cfg.in', - output: 'doxygen.cfg', - configuration: cdata, - install: false) +private_headers = [ + 'config.h', -doxygen = find_program('doxygen') -datadir = join_paths(get_option('datadir'), 'doc', 'libfprint-devel') -custom_target('docs', - input: cfg, - output: 'html', - command: [ doxygen, '@INPUT@' ], - install: true, - install_dir: datadir) + 'aeslib.h', + 'assembling.h', + 'fp_internal.h', + + # Drivers + 'aes1660.h', + 'aes2501.h', + 'aes2550.h', + 'aes2660.h', + 'aes3k.h', + 'aesx660.h', + 'driver_ids.h', + 'elan.h', + 'upeksonly.h', + 'upektc.h', + 'upektc_img.h', + 'vfs0050.h', + 'vfs301_proto_fragments.h', + 'vfs301_proto.h', + 'vfs5011_proto.h', + + # NBIS + 'morph.h', + 'sunrast.h', + 'bozorth.h', + 'defs.h', + 'log.h', + 'bz_array.h', + 'lfs.h', +] + +html_images = [ +] + +content_files = [ + 'intro.xml' +] + +expand_content_files = content_files + +glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix') +glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html') +docpath = join_paths(get_option('datadir'), 'gtk-doc', 'html') + +gnome.gtkdoc('libfprint', + main_xml: 'libfprint-docs.xml', + src_dir: join_paths(meson.source_root(), 'libfprint'), + dependencies: libfprint_dep, + content_files: content_files, + expand_content_files: expand_content_files, + scan_args: [ + '--rebuild-types', + '--ignore-decorators=API_EXPORTED', + '--ignore-headers=' + ' '.join(private_headers), + ], + fixxref_args: [ + '--html-dir=@0@'.format(docpath), + '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')), + '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')), + ], + html_assets: html_images, + install: true) diff --git a/doc/xml/gtkdocentities.ent.in b/doc/xml/gtkdocentities.ent.in new file mode 100644 index 00000000..f12c9ff7 --- /dev/null +++ b/doc/xml/gtkdocentities.ent.in @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/doc/xml/meson.build b/doc/xml/meson.build new file mode 100644 index 00000000..ea3ddf59 --- /dev/null +++ b/doc/xml/meson.build @@ -0,0 +1,10 @@ +ent_conf = configuration_data() +ent_conf.set('PACKAGE', 'libfprint') +ent_conf.set('PACKAGE_BUGREPORT', 'https://bugs.freedesktop.org/enter_bug.cgi?product=libfprint') +ent_conf.set('PACKAGE_NAME', 'libfprint') +ent_conf.set('PACKAGE_STRING', 'libfprint') +ent_conf.set('PACKAGE_TARNAME', 'libfprint-' + meson.project_version()) +ent_conf.set('PACKAGE_URL', 'https://www.freedesktop.org/wiki/Software/fprint/libfprint/') +ent_conf.set('PACKAGE_VERSION', meson.project_version()) +ent_conf.set('PACKAGE_API_VERSION', '1.0') +configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf) diff --git a/libfprint/async.c b/libfprint/async.c index 128b7e90..2337a579 100644 --- a/libfprint/async.c +++ b/libfprint/async.c @@ -36,7 +36,15 @@ void fpi_drvcb_open_complete(struct fp_dev *dev, int status) dev->open_cb(dev, status, dev->open_cb_data); } -API_EXPORTED int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb cb, +/** + * fp_async_dev_open: + * @ddev: + * @callback: + * @user_data + * + * Returns: + */ +API_EXPORTED int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback, void *user_data) { struct fp_driver *drv = ddev->drv; @@ -56,7 +64,7 @@ API_EXPORTED int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb cb, dev->udev = udevh; dev->__enroll_stage = -1; dev->state = DEV_STATE_INITIALIZING; - dev->open_cb = cb; + dev->open_cb = callback; dev->open_cb_data = user_data; if (!drv->open) { @@ -87,6 +95,12 @@ void fpi_drvcb_close_complete(struct fp_dev *dev) g_free(dev); } +/** + * fp_async_dev_close: + * @dev: + * @callback: + * @user_data + */ API_EXPORTED void fp_async_dev_close(struct fp_dev *dev, fp_dev_close_cb callback, void *user_data) { @@ -127,6 +141,14 @@ void fpi_drvcb_enroll_started(struct fp_dev *dev, int status) } } +/** + * fp_async_enroll_start: + * @dev: + * @callback: + * @user_data: + * + * Returns: + */ API_EXPORTED int fp_async_enroll_start(struct fp_dev *dev, fp_enroll_stage_cb callback, void *user_data) { @@ -181,6 +203,14 @@ void fpi_drvcb_enroll_stopped(struct fp_dev *dev) dev->enroll_stop_cb(dev, dev->enroll_stop_cb_data); } +/** + * fp_async_enroll_stop: + * @dev: + * @callback: + * @user_data: + * + * Returns: + */ API_EXPORTED int fp_async_enroll_stop(struct fp_dev *dev, fp_enroll_stop_cb callback, void *user_data) { @@ -210,6 +240,15 @@ API_EXPORTED int fp_async_enroll_stop(struct fp_dev *dev, return r; } +/** + * fp_async_verify_start: + * @dev: + * @data: + * @callback: + * @user_data: + * + * Returns: + */ API_EXPORTED int fp_async_verify_start(struct fp_dev *dev, struct fp_print_data *data, fp_verify_cb callback, void *user_data) { @@ -278,6 +317,14 @@ void fpi_drvcb_verify_stopped(struct fp_dev *dev) dev->verify_stop_cb(dev, dev->verify_stop_cb_data); } +/** + * fp_async_verify_stop: + * @dev: + * @callback: + * @user_data: + * + * Returns: + */ API_EXPORTED int fp_async_verify_stop(struct fp_dev *dev, fp_verify_stop_cb callback, void *user_data) { @@ -311,6 +358,15 @@ API_EXPORTED int fp_async_verify_stop(struct fp_dev *dev, return r; } +/** + * fp_async_identify_start: + * @dev: + * @gallery: + * @callback: + * @user_data: + * + * Returns: + */ API_EXPORTED int fp_async_identify_start(struct fp_dev *dev, struct fp_print_data **gallery, fp_identify_cb callback, void *user_data) { @@ -369,6 +425,14 @@ void fpi_drvcb_report_identify_result(struct fp_dev *dev, int result, fp_dbg("ignoring verify result as no callback is subscribed"); } +/** + * fp_async_identify_stop: + * @dev: + * @callback: + * @user_data: + * + * Returns: + */ API_EXPORTED int fp_async_identify_stop(struct fp_dev *dev, fp_identify_stop_cb callback, void *user_data) { @@ -412,6 +476,15 @@ void fpi_drvcb_identify_stopped(struct fp_dev *dev) dev->identify_stop_cb(dev, dev->identify_stop_cb_data); } +/** + * fp_async_capture_start: + * @dev: + * @unconditional: + * @callback: + * @user_data: + * + * Returns: + */ API_EXPORTED int fp_async_capture_start(struct fp_dev *dev, int unconditional, fp_capture_cb callback, void *user_data) { @@ -479,6 +552,14 @@ void fpi_drvcb_capture_stopped(struct fp_dev *dev) dev->capture_stop_cb(dev, dev->capture_stop_cb_data); } +/** + * fp_async_capture_stop: + * @dev: + * @callback: + * @user_data: + * + * Returns: + */ API_EXPORTED int fp_async_capture_stop(struct fp_dev *dev, fp_capture_stop_cb callback, void *user_data) { diff --git a/libfprint/core.c b/libfprint/core.c index 6f3729e2..e22b3bb5 100644 --- a/libfprint/core.c +++ b/libfprint/core.c @@ -34,163 +34,50 @@ libusb_context *fpi_usb_ctx = NULL; GSList *opened_devices = NULL; /** - * \mainpage libfprint API Reference - * libfprint is an open source library to provide access to fingerprint - * scanning devices. For more info, see the - * libfprint project - * homepage. + * SECTION:discovery + * @title: Device discovery * - * This documentation is aimed at application developers who wish to integrate - * fingerprint-related functionality into their software. libfprint has been - * designed so that you only have to do this once - by integrating your - * software with libfprint, you'll be supporting all the fingerprint readers - * that we have got our hands on. As such, the API is rather general (and - * therefore hopefully easy to comprehend!), and does its best to hide the - * technical details that required to operate the hardware. + * These functions allow you to scan the system for supported fingerprint + * scanning hardware. This is your starting point when integrating libfprint + * into your software. * - * This documentation is not aimed at developers wishing to develop and - * contribute fingerprint device drivers to libfprint. - * - * Feedback on this API and its associated documentation is appreciated. Was - * anything unclear? Does anything seem unreasonably complicated? Is anything - * missing? Let us know on the - * mailing list. - * - * \section enrollment Enrollment - * - * Before you dive into the API, it's worth introducing a couple of concepts. - * - * The process of enrolling a finger is where you effectively scan your - * finger for the purposes of teaching the system what your finger looks like. - * This means that you scan your fingerprint, then the system processes it and - * stores some data about your fingerprint to refer to later. - * - * \section verification Verification - * - * Verification is what most people think of when they think about fingerprint - * scanning. The process of verification is effectively performing a fresh - * fingerprint scan, and then comparing that scan to a finger that was - * previously enrolled. - * - * As an example scenario, verification can be used to implement what people - * would picture as fingerprint login (i.e. fingerprint replaces password). - * For example: - * - I enroll my fingerprint through some software that trusts I am who I say - * I am. This is a prerequisite before I can perform fingerprint-based - * login for my account. - * - Some time later, I want to login to my computer. I enter my username, - * but instead of prompting me for a password, it asks me to scan my finger. - * I scan my finger. - * - The system compares the finger I just scanned to the one that was - * enrolled earlier. If the system decides that the fingerprints match, - * I am successfully logged in. Otherwise, the system informs me that I am - * not authorised to login as that user. - * - * \section identification Identification - * - * Identification is the process of comparing a freshly scanned fingerprint - * to a collection of previously enrolled fingerprints. For example, - * imagine there are 100 people in an organisation, and they all have enrolled - * their fingerprints. One user walks up to a fingerprint scanner and scans - * their finger. With no other knowledge of who that user might be, - * the system examines their fingerprint, looks in the database, and determines - * that the user is user number #61. - * - * In other words, verification might be seen as a one-to-one fingerprint - * comparison where you know the identity of the user that you wish to - * authenticate, whereas identification is a one-to-many comparison where you - * do not know the identity of the user that you wish to authenticate. - * - * \section compat_general Device and print compatibility - * Moving off generic conceptual ideas and onto libfprint-specific - * implementation details, here are some introductory notes regarding how - * libfprint copes with compatibility of fingerprints. - * - * libfprint deals with a whole variety of different fingerprint readers and - * the design includes considerations of compatibility and interoperability - * between multiple devices. Your application should also be prepared to - * work with more than one type of fingerprint reader and should consider that - * enrolled fingerprint X may not be compatible with the device the user has - * plugged in today. - * - * libfprint implements the principle that fingerprints from different devices - * are not necessarily compatible. For example, different devices may see - * significantly different areas of fingerprint surface, and comparing images - * between the devices would be unreliable. Also, devices can stretch and - * distort images in different ways. - * - * libfprint also implements the principle that in some cases, fingerprints - * are compatible between different devices. If you go and buy two - * identical fingerprint readers, it seems logical that you should be able - * to enroll on one and verify on another without problems. - * - * libfprint takes a fairly simplistic approach to these issues. Internally, - * fingerprint hardware is driven by individual drivers. libfprint enforces - * that a fingerprint that came from a device backed by driver X is never - * compared to a fingerprint that came from a device backed by driver Y. - * - * Additionally, libfprint is designed for the situation where a single driver - * may support a range of devices which differ in imaging or scanning - * properties. For example, a driver may support two ranges of devices which - * even though are programmed over the same interface, one device sees - * substantially less of the finger flesh, therefore images from the two - * device types should be incompatible despite being from the same driver. To - * implement this, each driver assigns a device type to each device - * that it detects based on its imaging characteristics. libfprint ensures that - * two prints being compared have the same device type. - * - * In summary, libfprint represents fingerprints in several internal structures - * and each representation will offer you a way of determining the - * \ref driver_id "driver ID" and \ref devtype "devtype" of the print in - * question. Prints are only compatible if the driver ID and devtypes - * match. libfprint does offer you some "is this print compatible?" helper - * functions, so you don't have to worry about these details too much. - * - * \section sync Synchronity/asynchronity - * - * Currently, all data acquisition operations are synchronous and can - * potentially block for extended periods of time. For example, the enroll - * function will block for an unpredictable amount of time until the user - * scans their finger. - * - * Alternative asynchronous/non-blocking functionality will be offered in - * future but has not been implemented yet. - * - * \section getting_started Getting started - * - * libfprint includes several simple functional examples under the examples/ - * directory in the libfprint source distribution. Those are good starting - * points. - * - * Usually the first thing you want to do is determine which fingerprint - * devices are present. This is done through \ref dscv_dev "device discovery". - * - * Once you have found a device you would like to operate, you should open it. - * Refer to \ref dev "device operations". This section also details enrollment, - * image capture, and verification. - * - * - * That should be enough to get you started, but do remember there are - * documentation pages on other aspects of libfprint's API (see the modules - * page). + * When you've identified a discovered device that you would like to control, + * you can open it with fp_dev_open(). Note that discovered devices may no + * longer be available at the time when you want to open them, for example + * the user may have unplugged the device. */ -/** @defgroup core Core library operations */ +/** + * SECTION:drv + * @title: Driver operations + * + * Internally, libfprint is abstracted into various drivers to communicate + * with the different types of supported fingerprint readers. libfprint works + * hard so that you don't have to care about these internal abstractions, + * however there are some situations where you may be interested in a little + * behind-the-scenes driver info. + * + * You can obtain the driver for a device using fp_dev_get_driver(), which + * you can pass to the functions documented on this page. + */ /** - * @defgroup dev Device operations + * SECTION:dev + * @title: Devices operations + * * In order to interact with fingerprint scanners, your software will * interface primarily with libfprint's representation of devices, detailed * on this page. * - * \section enrolling Enrolling + * # Enrolling # {#enrolling} + * * Enrolling is represented within libfprint as a multi-stage process. This * slightly complicates things for application developers, but is required * for a smooth process. * * Some devices require the user to scan their finger multiple times in * order to complete the enrollment process. libfprint must return control - * to your application inbetween each scan in order for your application to + * to your application in-between each scan in order for your application to * instruct the user to swipe their finger again. Each scan is referred to * as a stage, so a device that requires 3 scans for enrollment corresponds * to you running 3 enrollment stages using libfprint. @@ -208,7 +95,8 @@ GSList *opened_devices = NULL; * fp_enroll_finger() documentation. You should pay careful attention to the * details. * - * \section imaging Imaging + * # Imaging # {#imaging} + * * libfprint provides you with some ways to retrieve images of scanned * fingers, such as the fp_dev_img_capture() function, or some enroll/verify * function variants which provide images. You may wish to do something with @@ -224,59 +112,6 @@ GSList *opened_devices = NULL; * on a particular device. Your application must be able to cope with the * fact that libfprint does support regular operations (e.g. enrolling and * verification) on some devices which do not provide images. - * - * \section devtype Devtypes - * Internally, the \ref drv "driver" behind a device assigns a 32-bit - * devtype identifier to the device. This cannot be used as a unique - * ID for a specific device as many devices under the same range may share - * the same devtype. The devtype may even be 0 in all cases. - * - * The only reason you may be interested in retrieving the devtype for a - * device is for the purpose of checking if some print data is compatible - * with a device. libfprint uses the devtype as one way of checking that the - * print you are verifying is compatible with the device in question - the - * devtypes must be equal. This effectively allows drivers to support more - * than one type of device where the data from each one is not compatible with - * the other. Note that libfprint does provide you with helper functions to - * determine whether a print is compatible with a device, so under most - * circumstances, you don't have to worry about devtypes at all. - */ - -/** @defgroup dscv_dev Device discovery - * These functions allow you to scan the system for supported fingerprint - * scanning hardware. This is your starting point when integrating libfprint - * into your software. - * - * When you've identified a discovered device that you would like to control, - * you can open it with fp_dev_open(). Note that discovered devices may no - * longer be available at the time when you want to open them, for example - * the user may have unplugged the device. - */ - -/** @defgroup drv Driver operations - * Internally, libfprint is abstracted into various drivers to communicate - * with the different types of supported fingerprint readers. libfprint works - * hard so that you don't have to care about these internal abstractions, - * however there are some situations where you may be interested in a little - * behind-the-scenes driver info. - * - * You can obtain the driver for a device using fp_dev_get_driver(), which - * you can pass to the functions documented on this page. - * - * \section driver_id Driver IDs - * Each driver is assigned a unique ID by the project maintainer. These - * assignments are - * - * documented on the wiki and will never change. - * - * The only reason you may be interested in retrieving the driver ID for a - * driver is for the purpose of checking if some print data is compatible - * with a device. libfprint uses the driver ID as one way of checking that - * the print you are trying to verify is compatible with the device in - * question - it ensures that enrollment data from one driver is never fed to - * another. Note that libfprint does provide you with helper functions to - * determine whether a print is compatible with a device, so under most - * circumstances, you don't have to worry about driver IDs at all. */ static GSList *registered_drivers = NULL; @@ -524,10 +359,13 @@ static struct fp_dscv_dev *discover_dev(libusb_device *udev) return ddev; } -/** \ingroup dscv_dev +/** + * fp_discover_devs: + * * Scans the system and returns a list of discovered devices. This is your * entry point into finding a fingerprint reader to operate. - * \returns a NULL-terminated list of discovered devices. Must be freed with + * + * Returns: a %NULL-terminated list of discovered devices. Must be freed with * fp_dscv_devs_free() after use. */ API_EXPORTED struct fp_dscv_dev **fp_discover_devs(void) @@ -582,12 +420,14 @@ API_EXPORTED struct fp_dscv_dev **fp_discover_devs(void) return list; } -/** \ingroup dscv_dev +/** + * fp_dscv_devs_free: + * @devs: the list of discovered devices. If %NULL, function simply + * returns. + * * Free a list of discovered devices. This function destroys the list and all * discovered devices that it included, so make sure you have opened your - * discovered device before freeing the list. - * \param devs the list of discovered devices. If NULL, function simply - * returns. + * discovered device before freeing the list. */ API_EXPORTED void fp_dscv_devs_free(struct fp_dscv_dev **devs) { @@ -602,20 +442,26 @@ API_EXPORTED void fp_dscv_devs_free(struct fp_dscv_dev **devs) g_free(devs); } -/** \ingroup dscv_dev - * Gets the \ref drv "driver" for a discovered device. - * \param dev the discovered device - * \returns the driver backing the device +/** + * fp_dscv_dev_get_driver: + * @dev: the discovered device + * + * Gets the #fp_driver "driver" for a discovered device. + * + * Returns: the driver backing the device */ API_EXPORTED struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev) { return dev->drv; } -/** \ingroup dscv_dev - * Gets the \ref devtype "devtype" for a discovered device. - * \param dev the discovered device - * \returns the devtype of the device +/** + * fp_dscv_dev_get_devtype: + * @dev: the discovered device + * + * Gets the [devtype](advanced-topics.html#device-types) for a discovered device. + * + * Returns: the devtype of the device */ API_EXPORTED uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev) { @@ -635,62 +481,74 @@ enum fp_print_data_type fpi_driver_get_data_type(struct fp_driver *drv) } } -/** \ingroup dscv_dev - * Determines if a specific \ref print_data "stored print" appears to be +/** + * fp_dscv_dev_supports_print_data: + * @dev: the discovered device + * @print: the print for compatibility checking + * + * Determines if a specific #fp_print_data "stored print" appears to be * compatible with a discovered device. - * \param dev the discovered device - * \param data the print for compatibility checking - * \returns 1 if the print is compatible with the device, 0 otherwise + * + * Returns: 1 if the print is compatible with the device, 0 otherwise */ API_EXPORTED int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev, - struct fp_print_data *data) + struct fp_print_data *print) { return fpi_print_data_compatible(dev->drv->id, dev->devtype, - fpi_driver_get_data_type(dev->drv), data->driver_id, data->devtype, - data->type); + fpi_driver_get_data_type(dev->drv), print->driver_id, print->devtype, + print->type); } -/** \ingroup dscv_dev - * Determines if a specific \ref dscv_print "discovered print" appears to be +/** + * fp_dscv_dev_supports_dscv_print: + * @dev: the discovered device + * @print: the discovered print for compatibility checking + * + * Determines if a specific #fp_dscv_print "discovered print" appears to be * compatible with a discovered device. - * \param dev the discovered device - * \param data the discovered print for compatibility checking - * \returns 1 if the print is compatible with the device, 0 otherwise + * + * Returns: 1 if the print is compatible with the device, 0 otherwise */ API_EXPORTED int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev, - struct fp_dscv_print *data) + struct fp_dscv_print *print) { return fpi_print_data_compatible(dev->drv->id, dev->devtype, 0, - data->driver_id, data->devtype, 0); + print->driver_id, print->devtype, 0); } -/** \ingroup dscv_dev +/** + * fp_dscv_dev_for_print_data: + * @devs: a list of discovered devices + * @print: the print under inspection + * * Searches a list of discovered devices for a device that appears to be - * compatible with a \ref print_data "stored print". - * \param devs a list of discovered devices - * \param data the print under inspection - * \returns the first discovered device that appears to support the print, or - * NULL if no apparently compatible devices could be found + * compatible with a #fp_print_data "stored print". + * + * Returns: the first discovered device that appears to support the print, or + * %NULL if no apparently compatible devices could be found */ API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs, - struct fp_print_data *data) + struct fp_print_data *print) { struct fp_dscv_dev *ddev; int i; for (i = 0; (ddev = devs[i]); i++) - if (fp_dscv_dev_supports_print_data(ddev, data)) + if (fp_dscv_dev_supports_print_data(ddev, print)) return ddev; return NULL; } -/** \ingroup dscv_dev +/** + * fp_dscv_dev_for_dscv_print: + * @devs: a list of discovered devices + * @print: the print under inspection + * * Searches a list of discovered devices for a device that appears to be - * compatible with a \ref dscv_print "discovered print". - * \param devs a list of discovered devices - * \param print the print under inspection - * \returns the first discovered device that appears to support the print, or - * NULL if no apparently compatible devices could be found + * compatible with a #fp_dscv_print "discovered print". + * + * Returns: the first discovered device that appears to support the print, or + * %NULL if no apparently compatible devices could be found */ API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs, struct fp_dscv_print *print) @@ -704,42 +562,54 @@ API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev * return NULL; } -/** \ingroup dev - * Get the \ref drv "driver" for a fingerprint device. - * \param dev the device - * \returns the driver controlling the device +/** + * fp_dev_get_driver: + * @dev: the device + * + * Get the #fp_driver "driver" for a fingerprint device. + * + * Returns: the driver controlling the device */ API_EXPORTED struct fp_driver *fp_dev_get_driver(struct fp_dev *dev) { return dev->drv; } -/** \ingroup dev - * Gets the number of \ref enrolling "enroll stages" required to enroll a +/** + * fp_dev_get_nr_enroll_stages: + * @dev: the device + * + * Gets the number of [enroll stages](intro.html#enrollment) required to enroll a * fingerprint with the device. - * \param dev the device - * \returns the number of enroll stages + * + * Returns: the number of enroll stages */ API_EXPORTED int fp_dev_get_nr_enroll_stages(struct fp_dev *dev) { return dev->nr_enroll_stages; } -/** \ingroup dev - * Gets the \ref devtype "devtype" for a device. - * \param dev the device - * \returns the devtype +/** + * fp_dev_get_devtype: + * @dev: the device + * + * Gets the [devtype](advanced-topics.html#device-types) for a device. + * + * Returns: the devtype */ API_EXPORTED uint32_t fp_dev_get_devtype(struct fp_dev *dev) { return dev->devtype; } -/** \ingroup dev +/** + * fp_dev_supports_print_data: + * @dev: the device + * @data: the stored print + * * Determines if a stored print is compatible with a certain device. - * \param dev the device - * \param data the stored print - * \returns 1 if the print is compatible with the device, 0 if not + * + * Returns: 1 if the print is compatible with the device, 0 if not */ API_EXPORTED int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data) @@ -749,54 +619,69 @@ API_EXPORTED int fp_dev_supports_print_data(struct fp_dev *dev, data->type); } -/** \ingroup dev - * Determines if a \ref dscv_print "discovered print" appears to be compatible +/** + * fp_dev_supports_dscv_print: + * @dev: the device + * @print: the discovered print + * + * Determines if a #fp_dscv_print "discovered print" appears to be compatible * with a certain device. - * \param dev the device - * \param data the discovered print - * \returns 1 if the print is compatible with the device, 0 if not + * + * Returns: 1 if the print is compatible with the device, 0 if not */ API_EXPORTED int fp_dev_supports_dscv_print(struct fp_dev *dev, - struct fp_dscv_print *data) + struct fp_dscv_print *print) { return fpi_print_data_compatible(dev->drv->id, dev->devtype, - 0, data->driver_id, data->devtype, 0); + 0, print->driver_id, print->devtype, 0); } -/** \ingroup drv +/** + * fp_driver_get_name: + * @drv: the driver + * * Retrieves the name of the driver. For example: "upekts" - * \param drv the driver - * \returns the driver name. Must not be modified or freed. + * + * Returns: the driver name. Must not be modified or freed. */ API_EXPORTED const char *fp_driver_get_name(struct fp_driver *drv) { return drv->name; } -/** \ingroup drv +/** + * fp_driver_get_full_name: + * @drv: the driver + * * Retrieves a descriptive name of the driver. For example: "UPEK TouchStrip" - * \param drv the driver - * \returns the descriptive name. Must not be modified or freed. + * + * Returns: the descriptive name. Must not be modified or freed. */ API_EXPORTED const char *fp_driver_get_full_name(struct fp_driver *drv) { return drv->full_name; } -/** \ingroup drv +/** + * fp_driver_get_driver_id: + * @drv: the driver + * * Retrieves the driver ID code for a driver. - * \param drv the driver - * \returns the driver ID + * + * Returns: the driver ID */ API_EXPORTED uint16_t fp_driver_get_driver_id(struct fp_driver *drv) { return drv->id; } -/** \ingroup drv +/** + * fp_driver_get_scan_type: + * @drv: the driver + * * Retrieves the scan type for the devices associated with the driver. - * \param drv the driver - * \returns the scan type + * + * Returns: the scan type */ API_EXPORTED enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv) { @@ -810,14 +695,17 @@ static struct fp_img_dev *dev_to_img_dev(struct fp_dev *dev) return dev->priv; } -/** \ingroup dev +/** + * fp_dev_supports_imaging: + * @dev: the fingerprint device + * * Determines if a device has imaging capabilities. If a device has imaging * capabilities you are able to perform imaging operations such as retrieving * scan images using fp_dev_img_capture(). However, not all devices are * imaging devices - some do all processing in hardware. This function will * indicate which class a device in question falls into. - * \param dev the fingerprint device - * \returns 1 if the device is an imaging device, 0 if the device does not + * + * Returns: 1 if the device is an imaging device, 0 if the device does not * provide images to the host computer */ API_EXPORTED int fp_dev_supports_imaging(struct fp_dev *dev) @@ -825,25 +713,31 @@ API_EXPORTED int fp_dev_supports_imaging(struct fp_dev *dev) return dev->drv->capture_start != NULL; } -/** \ingroup dev - * Determines if a device is capable of \ref identification "identification" +/** + * fp_dev_supports_identification: + * @dev: the fingerprint device + * + * Determines if a device is capable of [identification](intro.html#identification) * through fp_identify_finger() and similar. Not all devices support this * functionality. - * \param dev the fingerprint device - * \returns 1 if the device is capable of identification, 0 otherwise. + * + * Returns: 1 if the device is capable of identification, 0 otherwise. */ API_EXPORTED int fp_dev_supports_identification(struct fp_dev *dev) { return dev->drv->identify_start != NULL; } -/** \ingroup dev +/** + * fp_dev_get_img_width: + * @dev: the fingerprint device + * * Gets the expected width of images that will be captured from the device. * This function will return -1 for devices that are not - * \ref imaging "imaging devices". If the width of images from this device + * [imaging devices](libfprint-Devices-operations.html#imaging). If the width of images from this device * can vary, 0 will be returned. - * \param dev the device - * \returns the expected image width, or 0 for variable, or -1 for non-imaging + * + * Returns: the expected image width, or 0 for variable, or -1 for non-imaging * devices. */ API_EXPORTED int fp_dev_get_img_width(struct fp_dev *dev) @@ -857,13 +751,16 @@ API_EXPORTED int fp_dev_get_img_width(struct fp_dev *dev) return fpi_imgdev_get_img_width(imgdev); } -/** \ingroup dev +/** + * fp_dev_get_img_height: + * @dev: the fingerprint device + * * Gets the expected height of images that will be captured from the device. * This function will return -1 for devices that are not - * \ref imaging "imaging devices". If the height of images from this device + * [imaging devices](libfprint-Devices-operations.html#imaging). If the height of images from this device * can vary, 0 will be returned. - * \param dev the device - * \returns the expected image height, or 0 for variable, or -1 for non-imaging + * + * Returns: the expected image height, or 0 for variable, or -1 for non-imaging * devices. */ API_EXPORTED int fp_dev_get_img_height(struct fp_dev *dev) @@ -877,7 +774,10 @@ API_EXPORTED int fp_dev_get_img_height(struct fp_dev *dev) return fpi_imgdev_get_img_height(imgdev); } -/** \ingroup core +/** + * fp_set_debug: + * @level: the verbosity level + * * Set message verbosity. * - Level 0: no messages ever printed by the library (default) * - Level 1: error messages are printed to stderr @@ -902,9 +802,6 @@ API_EXPORTED int fp_dev_get_img_height(struct fp_dev *dev) * * If libfprint was compiled with verbose debug message logging, this function * does nothing: you'll always get messages from all levels. - * - * \param ctx the context to operate on, or NULL for the default context - * \param level debug level to set */ API_EXPORTED void fp_set_debug(int level) { @@ -915,10 +812,13 @@ API_EXPORTED void fp_set_debug(int level) libusb_set_debug(fpi_usb_ctx, level); } -/** \ingroup core +/** + * fp_init: + * * Initialise libfprint. This function must be called before you attempt to * use the library in any way. - * \return 0 on success, non-zero on error. + * + * Returns: 0 on success, non-zero on error. */ API_EXPORTED int fp_init(void) { @@ -943,7 +843,9 @@ API_EXPORTED int fp_init(void) return 0; } -/** \ingroup core +/** + * fp_exit: + * * Deinitialise libfprint. This function should be called during your program * exit sequence. You must not use any libfprint functions after calling this * function, unless you call fp_init() again. diff --git a/libfprint/data.c b/libfprint/data.c index 70f020f7..92fd7be6 100644 --- a/libfprint/data.c +++ b/libfprint/data.c @@ -32,8 +32,11 @@ #define DIR_PERMS 0700 -/** @defgroup print_data Stored prints - * Stored prints are represented by a structure named fp_print_data. +/** + * SECTION: print_data + * @title: Stored prints + * + * Stored prints are represented by a structure named #fp_print_data. * Stored prints are originally obtained from an enrollment function such as * fp_enroll_finger(). * @@ -124,14 +127,17 @@ struct fp_print_data *fpi_print_data_new(struct fp_dev *dev) fpi_driver_get_data_type(dev->drv)); } -/** \ingroup print_data +/** + * fp_print_data_get_data: + * @data: the stored print + * @ret: output location for the data buffer. Must be freed with free() + * after use. + * Convert a stored print into a unified representation inside a data buffer. * You can then store this data buffer in any way that suits you, and load * it back at some later time using fp_print_data_from_data(). - * \param data the stored print - * \param ret output location for the data buffer. Must be freed with free() - * after use. - * \returns the size of the freshly allocated buffer, or 0 on error. + * + * Returns: the size of the freshly allocated buffer, or 0 on error. */ API_EXPORTED size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret) @@ -245,13 +251,16 @@ static struct fp_print_data *fpi_print_data_from_fp2_data(unsigned char *buf, } -/** \ingroup print_data +/** + * fp_print_data_from_data: + * @buf: the data buffer + * @buflen: the length of the buffer + * Load a stored print from a data buffer. The contents of said buffer must * be the untouched contents of a buffer previously supplied to you by the * fp_print_data_get_data() function. - * \param buf the data buffer - * \param buflen the length of the buffer - * \returns the stored print represented by the data, or NULL on error. Must + * + * Returns: the stored print represented by the data, or %NULL on error. Must * be freed with fp_print_data_free() after use. */ API_EXPORTED struct fp_print_data *fp_print_data_from_data(unsigned char *buf, @@ -305,7 +314,11 @@ static char *get_path_to_print(struct fp_dev *dev, enum fp_finger finger) return __get_path_to_print(dev->drv->id, dev->devtype, finger); } -/** \ingroup print_data +/** + * fp_print_data_save: + * @data: the stored print to save to disk + * @finger: the finger that this print corresponds to + * * Saves a stored print to disk, assigned to a specific finger. Even though * you are limited to storing only the 10 human fingers, this is a * per-device-type limit. For example, you can store the users right index @@ -316,9 +329,8 @@ static char *get_path_to_print(struct fp_dev *dev, enum fp_finger finger) * This function will unconditionally overwrite a fingerprint previously * saved for the same finger and device type. The print is saved in a hidden * directory beneath the current user's home directory. - * \param data the stored print to save to disk - * \param finger the finger that this print corresponds to - * \returns 0 on success, non-zero on error. + * + * Returns: 0 on success, non-zero on error. */ API_EXPORTED int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger) @@ -415,7 +427,13 @@ static int load_from_file(char *path, struct fp_print_data **data) return 0; } -/** \ingroup print_data +/** + * fp_print_data_load: + * @dev: the device you are loading the print for + * @finger: the finger of the file you are loading + * @data: output location to put the corresponding stored print. Must be + * freed with fp_print_data_free() after use. + * Loads a previously stored print from disk. The print must have been saved * earlier using the fp_print_data_save() function. * @@ -423,11 +441,7 @@ static int load_from_file(char *path, struct fp_print_data **data) * be found. Other error codes (both positive and negative) are possible for * obscure error conditions (e.g. corruption). * - * \param dev the device you are loading the print for - * \param finger the finger of the file you are loading - * \param data output location to put the corresponding stored print. Must be - * freed with fp_print_data_free() after use. - * \returns 0 on success, non-zero on error + * Returns: 0 on success, non-zero on error */ API_EXPORTED int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger, struct fp_print_data **data) @@ -455,11 +469,14 @@ API_EXPORTED int fp_print_data_load(struct fp_dev *dev, return 0; } -/** \ingroup print_data +/** + * fp_print_data_delete: + * @dev: the device that the print belongs to + * @finger: the finger of the file you are deleting + * Removes a stored print from disk previously saved with fp_print_data_save(). - * \param dev the device that the print belongs to - * \param finger the finger of the file you are deleting - * \returns 0 on success, negative on error + * + * Returns: 0 on success, negative on error */ API_EXPORTED int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger) @@ -477,18 +494,20 @@ API_EXPORTED int fp_print_data_delete(struct fp_dev *dev, return r; } -/** \ingroup print_data - * Attempts to load a stored print based on a \ref dscv_print +/** + * fp_print_data_from_dscv_print: + * @print: the discovered print + * @data: output location to point to the corresponding stored print. Must + * be freed with fp_print_data_free() after use. + + * Attempts to load a stored print based on a #fp_dscv_print * "discovered print" record. * * A return code of -ENOENT indicates that the file referred to by the * discovered print could not be found. Other error codes (both positive and * negative) are possible for obscure error conditions (e.g. corruption). * - * \param print the discovered print - * \param data output location to point to the corresponding stored print. Must - * be freed with fp_print_data_free() after use. - * \returns 0 on success, non-zero on error. + * Returns: 0 on success, non-zero on error. */ API_EXPORTED int fp_print_data_from_dscv_print(struct fp_dscv_print *print, struct fp_print_data **data) @@ -496,9 +515,11 @@ API_EXPORTED int fp_print_data_from_dscv_print(struct fp_dscv_print *print, return load_from_file(print->path, data); } -/** \ingroup print_data +/** + * fp_print_data_free: + * @data: the stored print to destroy. If NULL, function simply returns. + * * Frees a stored print. Must be called when you are finished using the print. - * \param data the stored print to destroy. If NULL, function simply returns. */ API_EXPORTED void fp_print_data_free(struct fp_print_data *data) { @@ -507,31 +528,40 @@ API_EXPORTED void fp_print_data_free(struct fp_print_data *data) g_free(data); } -/** \ingroup print_data - * Gets the \ref driver_id "driver ID" for a stored print. The driver ID +/** + * fp_print_data_get_driver_id: + * @data: the stored print + + * Gets the [driver ID](advanced-topics.html#driver_id) for a stored print. The driver ID * indicates which driver the print originally came from. The print is * only usable with a device controlled by that driver. - * \param data the stored print - * \returns the driver ID of the driver compatible with the print + * + * Returns: the driver ID of the driver compatible with the print */ API_EXPORTED uint16_t fp_print_data_get_driver_id(struct fp_print_data *data) { return data->driver_id; } -/** \ingroup print_data - * Gets the \ref devtype "devtype" for a stored print. The devtype represents +/** + * fp_print_data_get_devtype: + * @data: the stored print + + * Gets the [devtype](advanced-topics.html#device-types) for a stored print. The devtype represents * which type of device under the parent driver is compatible with the print. - * \param data the stored print - * \returns the devtype of the device range compatible with the print + * + * Returns: the devtype of the device range compatible with the print */ API_EXPORTED uint32_t fp_print_data_get_devtype(struct fp_print_data *data) { return data->devtype; } -/** @defgroup dscv_print Print discovery - * The \ref print_data "stored print" documentation detailed a simple API +/** + * SECTION:dscv_print + * @title: Print discovery + * + * The [stored print](libfprint-Stored-prints.html) documentation detailed a simple API * for storing per-device prints for a single user, namely * fp_print_data_save(). It also detailed a load function, * fp_print_data_load(), but usage of this function is limited to scenarios @@ -542,7 +572,7 @@ API_EXPORTED uint32_t fp_print_data_get_devtype(struct fp_print_data *data) * previously saved prints, potentially even before device discovery. These * functions are designed to offer this functionality to you. * - * Discovered prints are stored in a dscv_print structure, and you + * Discovered prints are stored in a #fp_dscv_print structure, and you * can use functions documented below to access some information about these * prints. You can determine if a discovered print appears to be compatible * with a device using functions such as fp_dscv_dev_supports_dscv_print() and @@ -643,10 +673,13 @@ static GSList *scan_driver_store_dir(char *drvpath, uint16_t driver_id, return list; } -/** \ingroup dscv_print +/** + * fp_discover_prints: + * * Scans the users home directory and returns a list of prints that were * previously saved using fp_print_data_save(). - * \returns a NULL-terminated list of discovered prints, must be freed with + * + * Returns: a %NULL-terminated list of discovered prints, must be freed with * fp_dscv_prints_free() after use. */ API_EXPORTED struct fp_dscv_print **fp_discover_prints(void) @@ -704,12 +737,14 @@ API_EXPORTED struct fp_dscv_print **fp_discover_prints(void) return list; } -/** \ingroup dscv_print +/** + * fp_dscv_prints_free: + * @prints: the list of discovered prints. If NULL, function simply + * returns. + * * Frees a list of discovered prints. This function also frees the discovered * prints themselves, so make sure you do not use any discovered prints * after calling this function. - * \param prints the list of discovered prints. If NULL, function simply - * returns. */ API_EXPORTED void fp_dscv_prints_free(struct fp_dscv_print **prints) { @@ -727,47 +762,59 @@ API_EXPORTED void fp_dscv_prints_free(struct fp_dscv_print **prints) g_free(prints); } -/** \ingroup dscv_print - * Gets the \ref driver_id "driver ID" for a discovered print. The driver ID +/** + * fp_dscv_print_get_driver_id: + * @print: the discovered print + * + * Gets the [driver ID](advanced-topics.html#driver_id) for a discovered print. The driver ID * indicates which driver the print originally came from. The print is only * usable with a device controlled by that driver. - * \param print the discovered print - * \returns the driver ID of the driver compatible with the print + * + * Returns: the driver ID of the driver compatible with the print */ API_EXPORTED uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print) { return print->driver_id; } -/** \ingroup dscv_print - * Gets the \ref devtype "devtype" for a discovered print. The devtype +/** + * fp_dscv_print_get_devtype: + * @print: the discovered print + * + * Gets the [devtype](advanced-topics.html#device-types) for a discovered print. The devtype * represents which type of device under the parent driver is compatible * with the print. - * \param print the discovered print - * \returns the devtype of the device range compatible with the print + * + * Returns: the devtype of the device range compatible with the print */ API_EXPORTED uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print) { return print->devtype; } -/** \ingroup dscv_print +/** + * fp_dscv_print_get_finger: + * @print: discovered print + * * Gets the finger code for a discovered print. - * \param print discovered print - * \returns a finger code from #fp_finger + * + * Returns: a finger code from #fp_finger */ API_EXPORTED enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print) { return print->finger; } -/** \ingroup dscv_print +/** + * fp_dscv_print_delete: + * @print: the discovered print to remove from disk + * * Removes a discovered print from disk. After successful return of this * function, functions such as fp_dscv_print_get_finger() will continue to * operate as before, however calling fp_print_data_from_dscv_print() will * fail for obvious reasons. - * \param print the discovered print to remove from disk - * \returns 0 on success, negative on error + * + * Returns: 0 on success, negative on error */ API_EXPORTED int fp_dscv_print_delete(struct fp_dscv_print *print) { diff --git a/libfprint/fprint.h b/libfprint/fprint.h index af1d686b..46017aca 100644 --- a/libfprint/fprint.h +++ b/libfprint/fprint.h @@ -27,42 +27,86 @@ extern "C" { #include #include -/* structs that applications are not allowed to peek into */ +/** + * fp_dscv_dev: + * + */ struct fp_dscv_dev; + +/** + * fp_dscv_print: + * + */ struct fp_dscv_print; + +/** + * fp_dev: + * + */ struct fp_dev; + +/** + * fp_driver: + * + */ struct fp_driver; + +/** + * fp_print_data: + * + */ struct fp_print_data; + +/** + * fp_img: + * + */ struct fp_img; /* misc/general stuff */ -/** \ingroup print_data +/** + * fp_finger: + * @LEFT_THUMB: Left thumb + * @LEFT_INDEX: Left index finger + * @LEFT_MIDDLE: Left middle finger + * @LEFT_RING: Left ring finger + * @LEFT_LITTLE: Left little finger + * @RIGHT_THUMB: Right thumb + * @RIGHT_INDEX: Right index finger + * @RIGHT_MIDDLE: Right middle finger + * @RIGHT_RING: Right ring finger + * @RIGHT_LITTLE: Right little finger + * * Numeric codes used to refer to fingers (and thumbs) of a human. These are * purposely not available as strings, to avoid getting the library tangled up * in localization efforts. */ enum fp_finger { - LEFT_THUMB = 1, /** thumb (left hand) */ - LEFT_INDEX, /** index finger (left hand) */ - LEFT_MIDDLE, /** middle finger (left hand) */ - LEFT_RING, /** ring finger (left hand) */ - LEFT_LITTLE, /** little finger (left hand) */ - RIGHT_THUMB, /** thumb (right hand) */ - RIGHT_INDEX, /** index finger (right hand) */ - RIGHT_MIDDLE, /** middle finger (right hand) */ - RIGHT_RING, /** ring finger (right hand) */ - RIGHT_LITTLE, /** little finger (right hand) */ + LEFT_THUMB = 1, + LEFT_INDEX, + LEFT_MIDDLE, + LEFT_RING, + LEFT_LITTLE, + RIGHT_THUMB, + RIGHT_INDEX, + RIGHT_MIDDLE, + RIGHT_RING, + RIGHT_LITTLE, }; -/** \ingroup dev +/** + * fp_scan_type: + * @FP_SCAN_TYPE_PRESS: the reader has a surface area that covers the whole finger + * @FP_SCAN_TYPE_SWIPE: the reader requires swiping the finger on a smaller area + * * Numeric codes used to refer to the scan type of the device. Devices require * either swiping or pressing the finger on the device. This is useful for * front-ends. */ enum fp_scan_type { - FP_SCAN_TYPE_PRESS = 0, /** press */ - FP_SCAN_TYPE_SWIPE, /** swipe */ + FP_SCAN_TYPE_PRESS = 0, + FP_SCAN_TYPE_SWIPE, }; /* Drivers */ @@ -85,6 +129,12 @@ struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs, struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs, struct fp_dscv_print *print); +/** + * fp_dscv_dev_get_driver_id: + * @dev: a discovered fingerprint device + * + * Returns: the ID for the underlying driver for that device + */ static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev) { return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev)); @@ -107,68 +157,75 @@ uint32_t fp_dev_get_devtype(struct fp_dev *dev); int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data); int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print); -/** \ingroup dev - * Image capture result codes returned from fp_dev_img_capture(). +/** + * fp_capture_result: + * Whether a capture failed or completed. + * + * @FP_CAPTURE_COMPLETE: Capture completed successfully, the capture data has been returned to the caller. + * @FP_CAPTURE_FAIL: Capture failed + * */ enum fp_capture_result { - /** Capture completed successfully, the capture data has been - * returned to the caller. */ FP_CAPTURE_COMPLETE = 0, - /** Capture failed for some reason */ FP_CAPTURE_FAIL, }; int fp_dev_supports_imaging(struct fp_dev *dev); int fp_dev_img_capture(struct fp_dev *dev, int unconditional, - struct fp_img **image); + struct fp_img **img); int fp_dev_get_img_width(struct fp_dev *dev); int fp_dev_get_img_height(struct fp_dev *dev); -/** \ingroup dev +/** + * fp_enroll_result: + * @FP_ENROLL_COMPLETE: Enrollment completed successfully, the enrollment data has been + * returned to the caller. + * @FP_ENROLL_FAIL: Enrollment failed due to incomprehensible data; this may occur when + * the user scans a different finger on each enroll stage. + * @FP_ENROLL_PASS: Enroll stage passed; more stages are need to complete the process. + * @FP_ENROLL_RETRY: The enrollment scan did not succeed due to poor scan quality or + * other general user scanning problem. + * @FP_ENROLL_RETRY_TOO_SHORT: The enrollment scan did not succeed because the finger swipe was + * too short. + * @FP_ENROLL_RETRY_CENTER_FINGER: The enrollment scan did not succeed because the finger was not + * centered on the scanner. + * @FP_ENROLL_RETRY_REMOVE_FINGER: The verification scan did not succeed due to quality or pressure + * problems; the user should remove their finger from the scanner before + * retrying. + * + * * Enrollment result codes returned from fp_enroll_finger(). * Result codes with RETRY in the name suggest that the scan failed due to * user error. Applications will generally want to inform the user of the * problem and then retry the enrollment stage. For more info on the semantics * of interpreting these result codes and tracking enrollment process, see - * \ref enrolling. + * [Enrolling](libfprint-Devices-operations.html#enrolling) */ enum fp_enroll_result { - /** Enrollment completed successfully, the enrollment data has been - * returned to the caller. */ FP_ENROLL_COMPLETE = 1, - /** Enrollment failed due to incomprehensible data; this may occur when - * the user scans a different finger on each enroll stage. */ FP_ENROLL_FAIL, - /** Enroll stage passed; more stages are need to complete the process. */ FP_ENROLL_PASS, - /** The enrollment scan did not succeed due to poor scan quality or - * other general user scanning problem. */ FP_ENROLL_RETRY = 100, - /** The enrollment scan did not succeed because the finger swipe was - * too short. */ FP_ENROLL_RETRY_TOO_SHORT, - /** The enrollment scan did not succeed because the finger was not - * centered on the scanner. */ FP_ENROLL_RETRY_CENTER_FINGER, - /** The verification scan did not succeed due to quality or pressure - * problems; the user should remove their finger from the scanner before - * retrying. */ FP_ENROLL_RETRY_REMOVE_FINGER, }; int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data, struct fp_img **img); -/** \ingroup dev - * Performs an enroll stage. See \ref enrolling for an explanation of enroll - * stages. This function is just a shortcut to calling fp_enroll_finger_img() - * with a NULL image parameter. Be sure to read the description of - * fp_enroll_finger_img() in order to understand its behaviour. - * - * \param dev the device - * \param print_data a location to return the resultant enrollment data from +/** + * fp_enroll_finger: + * @dev: the device + * @print_data: a location to return the resultant enrollment data from * the final stage. Must be freed with fp_print_data_free() after use. - * \return negative code on error, otherwise a code from #fp_enroll_result + * + * Performs an enroll stage. See [Enrolling](libfprint-Devices-operations.html#enrolling) + * for an explanation of enroll stages. This function is just a shortcut to + * calling fp_enroll_finger_img() with a %NULL image parameter. Be sure to read + * the description of fp_enroll_finger_img() in order to understand its behaviour. + * + * Returns: negative code on error, otherwise a code from #fp_enroll_result */ static inline int fp_enroll_finger(struct fp_dev *dev, struct fp_print_data **print_data) @@ -176,7 +233,23 @@ static inline int fp_enroll_finger(struct fp_dev *dev, return fp_enroll_finger_img(dev, print_data, NULL); } -/** \ingroup dev +/** + * fp_verify_result: + * @FP_VERIFY_NO_MATCH: The scan completed successfully, but the newly scanned fingerprint + * does not match the fingerprint being verified against. + * In the case of identification, this return code indicates that the + * scanned finger could not be found in the print gallery. + * @FP_VERIFY_MATCH: The scan completed successfully and the newly scanned fingerprint does + * match the fingerprint being verified, or in the case of identification, + * the scanned fingerprint was found in the print gallery. + * @FP_VERIFY_RETRY: The scan did not succeed due to poor scan quality or other general + * user scanning problem. + * @FP_VERIFY_RETRY_TOO_SHORT: The scan did not succeed because the finger swipe was too short. + * @FP_VERIFY_RETRY_CENTER_FINGER: The scan did not succeed because the finger was not centered on the + * scanner. + * @FP_VERIFY_RETRY_REMOVE_FINGER: The scan did not succeed due to quality or pressure problems; the user + * should remove their finger from the scanner before retrying. + * * Verification result codes returned from fp_verify_finger(). Return codes * are also shared with fp_identify_finger(). * Result codes with RETRY in the name suggest that the scan failed due to @@ -184,39 +257,28 @@ static inline int fp_enroll_finger(struct fp_dev *dev, * problem and then retry the verify operation. */ enum fp_verify_result { - /** The scan completed successfully, but the newly scanned fingerprint - * does not match the fingerprint being verified against. - * In the case of identification, this return code indicates that the - * scanned finger could not be found in the print gallery. */ FP_VERIFY_NO_MATCH = 0, - /** The scan completed successfully and the newly scanned fingerprint does - * match the fingerprint being verified, or in the case of identification, - * the scanned fingerprint was found in the print gallery. */ FP_VERIFY_MATCH = 1, - /** The scan did not succeed due to poor scan quality or other general - * user scanning problem. */ FP_VERIFY_RETRY = FP_ENROLL_RETRY, - /** The scan did not succeed because the finger swipe was too short. */ FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT, - /** The scan did not succeed because the finger was not centered on the - * scanner. */ FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER, - /** The scan did not succeed due to quality or pressure problems; the user - * should remove their finger from the scanner before retrying. */ FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER, }; int fp_verify_finger_img(struct fp_dev *dev, struct fp_print_data *enrolled_print, struct fp_img **img); -/** \ingroup dev +/** + * fp_verify_finger: + * @dev: the device to perform the scan. + * @enrolled_print: the print to verify against. Must have been previously + * enrolled with a device compatible to the device selected to perform the scan. + * * Performs a new scan and verify it against a previously enrolled print. This * function is just a shortcut to calling fp_verify_finger_img() with a NULL * image output parameter. - * \param dev the device to perform the scan. - * \param enrolled_print the print to verify against. Must have been previously - * enrolled with a device compatible to the device selected to perform the scan. - * \return negative code on error, otherwise a code from #fp_verify_result + * + * Returns: negative code on error, otherwise a code from #fp_verify_result * \sa fp_verify_finger_img() */ static inline int fp_verify_finger(struct fp_dev *dev, @@ -230,19 +292,22 @@ int fp_identify_finger_img(struct fp_dev *dev, struct fp_print_data **print_gallery, size_t *match_offset, struct fp_img **img); -/** \ingroup dev - * Performs a new scan and attempts to identify the scanned finger against a - * collection of previously enrolled fingerprints. This function is just a - * shortcut to calling fp_identify_finger_img() with a NULL image output - * parameter. - * \param dev the device to perform the scan. - * \param print_gallery NULL-terminated array of pointers to the prints to +/** + * fp_identify_finger: + * @dev: the device to perform the scan. + * @print_gallery: %NULL-terminated array of pointers to the prints to * identify against. Each one must have been previously enrolled with a device * compatible to the device selected to perform the scan. - * \param match_offset output location to store the array index of the matched + * @match_offset: output location to store the array index of the matched * gallery print (if any was found). Only valid if FP_VERIFY_MATCH was * returned. - * \return negative code on error, otherwise a code from #fp_verify_result + + * Performs a new scan and attempts to identify the scanned finger against a + * collection of previously enrolled fingerprints. This function is just a + * shortcut to calling fp_identify_finger_img() with a %NULL image output + * parameter. + * + * Returns: negative code on error, otherwise a code from #fp_verify_result * \sa fp_identify_finger_img() */ static inline int fp_identify_finger(struct fp_dev *dev, @@ -267,7 +332,11 @@ uint32_t fp_print_data_get_devtype(struct fp_print_data *data); /* Image handling */ -/** \ingroup img */ +/** + * fp_minutia: + * + * FIXME + */ struct fp_minutia { int x; int y; @@ -294,6 +363,10 @@ void fp_img_free(struct fp_img *img); /* Polling and timing */ +/** + * fp_pollfd: + * + */ struct fp_pollfd { int fd; short events; diff --git a/libfprint/img.c b/libfprint/img.c index 408dd564..09cd2300 100644 --- a/libfprint/img.c +++ b/libfprint/img.c @@ -28,19 +28,22 @@ #include "nbis/include/bozorth.h" #include "nbis/include/lfs.h" -/** @defgroup img Image operations +/** + * SECTION:img + * @title: Image operations + * * libfprint offers several ways of retrieving images from imaging devices, * one example being the fp_dev_img_capture() function. The functions * documented below allow you to work with such images. * - * \section img_fmt Image format + * # Image format # {#img_fmt} * All images are represented as 8-bit greyscale data. * - * \section img_std Image standardization + * # Image standardization # {#img_std} * In some contexts, images you are provided through libfprint are raw images * from the hardware. The orientation of these varies from device-to-device, * as does the color scheme (black-on-white or white-on-black?). libfprint - * provides the fp_img_standardize function to convert images into standard + * provides the fp_img_standardize() function to convert images into standard * form, which is defined to be: finger flesh as black on white surroundings, * natural upright orientation. */ @@ -82,9 +85,11 @@ struct fp_img *fpi_img_resize(struct fp_img *img, size_t newsize) return g_realloc(img, sizeof(*img) + newsize); } -/** \ingroup img +/** + * fp_img_free: + * @img: the image to destroy. If NULL, function simply returns. + * * Frees an image. Must be called when you are finished working with an image. - * \param img the image to destroy. If NULL, function simply returns. */ API_EXPORTED void fp_img_free(struct fp_img *img) { @@ -98,43 +103,55 @@ API_EXPORTED void fp_img_free(struct fp_img *img) g_free(img); } -/** \ingroup img +/** + * fp_img_get_height: + * @img: an image + * * Gets the pixel height of an image. - * \param img an image - * \returns the height of the image + * + * Returns: the height of the image */ API_EXPORTED int fp_img_get_height(struct fp_img *img) { return img->height; } -/** \ingroup img +/** + * fp_img_get_width: + * @img: an image + * * Gets the pixel width of an image. - * \param img an image - * \returns the width of the image + * + * Returns: the width of the image */ API_EXPORTED int fp_img_get_width(struct fp_img *img) { return img->width; } -/** \ingroup img +/** + * fp_img_get_data: + * @img: an image + * * Gets the greyscale data for an image. This data must not be modified or * freed, and must not be used after fp_img_free() has been called. - * \param img an image - * \returns a pointer to libfprint's internal data for the image + * + * Returns: a pointer to libfprint's internal data for the image */ API_EXPORTED unsigned char *fp_img_get_data(struct fp_img *img) { return img->data; } -/** \ingroup img +/** + * fp_img_save_to_file: + * @img: the image to save + * @path: the path to save the image. Existing files will be overwritten. + * * A quick convenience function to save an image to a file in - * PGM format. - * \param img the image to save - * \param path the path to save the image. Existing files will be overwritten. - * \returns 0 on success, non-zero on error. + * [PGM format](http://netpbm.sourceforge.net/doc/pgm.html). + * + * Returns: 0 on success, non-zero on error. */ API_EXPORTED int fp_img_save_to_file(struct fp_img *img, char *path) { @@ -209,12 +226,14 @@ static void invert_colors(struct fp_img *img) img->data[i] = 0xff - img->data[i]; } -/** \ingroup img - * \ref img_std "Standardizes" an image by normalizing its orientation, colors, +/** + * fp_img_standardize: + * @img: the image to standardize + * + * [Standardizes](libfprint-Image-operations.html#img_std) an image by normalizing its orientation, colors, * etc. It is safe to call this multiple times on an image, libfprint keeps * track of the work it needs to do to make an image standard and will not * perform these operations more than once for a given image. - * \param img the image to standardize */ API_EXPORTED void fp_img_standardize(struct fp_img *img) { @@ -419,23 +438,25 @@ int fpi_img_compare_print_data_to_gallery(struct fp_print_data *print, return FP_VERIFY_NO_MATCH; } -/** \ingroup img +/** + * fp_img_binarize: + * @img: a standardized image + * * Get a binarized form of a standardized scanned image. This is where the * fingerprint image has been "enhanced" and is a set of pure black ridges * on a pure white background. Internally, image processing happens on top * of the binarized image. * - * The image must have been \ref img_std "standardized" otherwise this function - * will fail. + * The image must have been [standardized](libfprint-Image-operations.html#img_std) + * otherwise this function will fail. * * It is safe to binarize an image and free the original while continuing * to use the binarized version. * * You cannot binarize an image twice. * - * \param img a standardized image - * \returns a new image representing the binarized form of the original, or - * NULL on error. Must be freed with fp_img_free() after use. + * Returns: a new image representing the binarized form of the original, or + * %NULL on error. Must be freed with fp_img_free() after use. */ API_EXPORTED struct fp_img *fp_img_binarize(struct fp_img *img) { @@ -467,15 +488,19 @@ API_EXPORTED struct fp_img *fp_img_binarize(struct fp_img *img) return ret; } -/** \ingroup img +/** + * fp_img_get_minutiae: + * @img: a standardized image + * @nr_minutiae: an output location to store minutiae list length + * * Get a list of minutiae detected in an image. A minutia point is a feature * detected on a fingerprint, typically where ridges end or split. * libfprint's image processing code relies upon comparing sets of minutiae, * so accurate placement of minutia points is critical for good imaging * performance. * - * The image must have been \ref img_std "standardized" otherwise this function - * will fail. + * The image must have been [standardized](libfprint-Image-operations.html#img_std) + * otherwise this function will fail. * * You cannot pass a binarized image to this function. Instead, pass the * original image. @@ -485,9 +510,7 @@ API_EXPORTED struct fp_img *fp_img_binarize(struct fp_img *img) * valid while the parent image has not been freed, and the minutiae data * must not be modified or freed. * - * \param img a standardized image - * \param nr_minutiae an output location to store minutiae list length - * \returns a list of minutiae points. Must not be modified or freed. + * Returns: a list of minutiae points. Must not be modified or freed. */ API_EXPORTED struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae) diff --git a/libfprint/poll.c b/libfprint/poll.c index e849ea4f..aad81d16 100644 --- a/libfprint/poll.c +++ b/libfprint/poll.c @@ -30,7 +30,9 @@ #include "fp_internal.h" /** - * @defgroup poll Polling and timing operations + * SECTION:events + * @title: Initialisation and events handling + * * These functions are only applicable to users of libfprint's asynchronous * API. * @@ -50,10 +52,10 @@ * If there are no events pending, fp_handle_events() will block for a few * seconds (and will handle any new events should anything occur in that time). * If you wish to customise this timeout, you can use - * fp_handle_events_timeout() instead. If you wish to do a nonblocking + * fp_handle_events_timeout() instead. If you wish to do a non-blocking * iteration, call fp_handle_events_timeout() with a zero timeout. * - * TODO: document how application is supposed to know when to call these + * FIXME: document how application is supposed to know when to call these * functions. */ @@ -192,14 +194,16 @@ static int handle_timeouts(void) return 0; } -/** \ingroup poll +/** + * fp_handle_events_timeout: + * @timeout: Maximum timeout for this blocking function + * * Handle any pending events. If a non-zero timeout is specified, the function * will potentially block for the specified amount of time, although it may * return sooner if events have been handled. The function acts as non-blocking * for a zero timeout. * - * \param timeout Maximum timeout for this blocking function - * \returns 0 on success, non-zero on error. + * Returns: 0 on success, non-zero on error. */ API_EXPORTED int fp_handle_events_timeout(struct timeval *timeout) { @@ -236,12 +240,14 @@ API_EXPORTED int fp_handle_events_timeout(struct timeval *timeout) return handle_timeouts(); } -/** \ingroup poll +/** + * fp_handle_events: + * * Convenience function for calling fp_handle_events_timeout() with a sensible * default timeout value of two seconds (subject to change if we decide another * value is more sensible). * - * \returns 0 on success, non-zero on error. + * Returns: 0 on success, non-zero on error. */ API_EXPORTED int fp_handle_events(void) { @@ -251,10 +257,14 @@ API_EXPORTED int fp_handle_events(void) return fp_handle_events_timeout(&tv); } -/* FIXME: docs - * returns 0 if no timeouts active - * returns 1 if timeout returned - * zero timeout means events are to be handled immediately */ +/** + * fp_get_next_timeout: + * @tv: a %timeval structure containing the duration to the next timeout. + * + * A zero filled @tv timeout means events are to be handled immediately + * + * Returns: returns 0 if no timeouts active, or 1 if timeout returned. + */ API_EXPORTED int fp_get_next_timeout(struct timeval *tv) { struct timeval fprint_timeout; @@ -286,16 +296,18 @@ API_EXPORTED int fp_get_next_timeout(struct timeval *tv) return 1; } -/** \ingroup poll +/** + * fp_get_pollfds: + * @pollfds: output location for a list of pollfds. If non-%NULL, must be + * released with free() when done. + * * Retrieve a list of file descriptors that should be polled for events * interesting to libfprint. This function is only for users who wish to * combine libfprint's file descriptor set with other event sources - more * simplistic users will be able to call fp_handle_events() or a variant * directly. * - * \param pollfds output location for a list of pollfds. If non-NULL, must be - * released with free() when done. - * \returns the number of pollfds in the resultant list, or negative on error. + * Returns: the number of pollfds in the resultant list, or negative on error. */ API_EXPORTED size_t fp_get_pollfds(struct fp_pollfd **pollfds) { @@ -326,7 +338,12 @@ API_EXPORTED size_t fp_get_pollfds(struct fp_pollfd **pollfds) return cnt; } -/* FIXME: docs */ +/** + * fp_set_pollfd_notifiers: + * @added_cb: + * @removed_cb: + * + */ API_EXPORTED void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb, fp_pollfd_removed_cb removed_cb) { diff --git a/libfprint/sync.c b/libfprint/sync.c index b3b28983..ad1a7946 100644 --- a/libfprint/sync.c +++ b/libfprint/sync.c @@ -37,12 +37,15 @@ static void sync_open_cb(struct fp_dev *dev, int status, void *user_data) odata->status = status; } -/** \ingroup dev +/** + * fp_dev_open: + * @ddev: the discovered device to open + * * Opens and initialises a device. This is the function you call in order - * to convert a \ref dscv_dev "discovered device" into an actual device handle + * to convert a #fp_dscv_dev "discovered device" into an actual device handle * that you can perform operations with. - * \param ddev the discovered device to open - * \returns the opened device handle, or NULL on error + * + * Returns: (transfer none): the opened device handle, or %NULL on error */ API_EXPORTED struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev) { @@ -76,10 +79,12 @@ static void sync_close_cb(struct fp_dev *dev, void *user_data) *closed = TRUE; } -/** \ingroup dev +/** + * fp_dev_close: + * @dev: the device to close. If %NULL, function simply returns. + * * Close a device. You must call this function when you are finished using * a fingerprint device. - * \param dev the device to close. If NULL, function simply returns. */ API_EXPORTED void fp_dev_close(struct fp_dev *dev) { @@ -120,9 +125,17 @@ static void enroll_stop_cb(struct fp_dev *dev, void *user_data) *stopped = TRUE; } -/** \ingroup dev - * Performs an enroll stage. See \ref enrolling for an explanation of enroll - * stages. +/** + * fp_enroll_finger_img: + * @dev: the device + * @print_data a location to return the resultant enrollment data from + * the final stage. Must be freed with fp_print_data_free() after use. + * @img: location to store the scan image. accepts %NULL for no image + * storage. If an image is returned, it must be freed with fp_img_free() after + * use. + * + * Performs an enroll stage. See [Enrolling](libfprint-Devices-operations.html#enrolling) + * for an explanation of enroll stages. * * If no enrollment is in process, this kicks of the process and runs the * first stage. If an enrollment is already in progress, calling this @@ -137,7 +150,7 @@ static void enroll_stop_cb(struct fp_dev *dev, void *user_data) * The RETRY codes from #fp_enroll_result may be returned from any enroll * stage. These codes indicate that the scan was not succesful in that the * user did not position their finger correctly or similar. When a RETRY code - * is returned, the enrollment stage is not advanced, so the next call + * is returned, the enrollment stage is not advanced, so the next call * into this function will retry the current stage again. The current stage may * need to be retried several times. * @@ -159,19 +172,13 @@ static void enroll_stop_cb(struct fp_dev *dev, void *user_data) * resultant enrollment data. The print_data parameter will not be modified * during any other enrollment stages, hence it is actually legal to pass NULL * as this argument for all but the final stage. - * + * * If the device is an imaging device, it can also return the image from * the scan, even when the enroll fails with a RETRY or FAIL code. It is legal * to call this function even on non-imaging devices, just don't expect them to * provide images. * - * \param dev the device - * \param print_data a location to return the resultant enrollment data from - * the final stage. Must be freed with fp_print_data_free() after use. - * \param img location to store the scan image. accepts NULL for no image - * storage. If an image is returned, it must be freed with fp_img_free() after - * use. - * \return negative code on error, otherwise a code from #fp_enroll_result + * Returns: negative code on error, otherwise a code from #fp_enroll_result */ API_EXPORTED int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data, struct fp_img **img) @@ -302,20 +309,22 @@ static void verify_stop_cb(struct fp_dev *dev, void *user_data) *stopped = TRUE; } -/** \ingroup dev +/** + * fp_verify_finger_img: + * @dev: the device to perform the scan. + * @enrolled_print: the print to verify against. Must have been previously + * enrolled with a device compatible to the device selected to perform the scan. + * @img: location to store the scan image. accepts %NULL for no image + * storage. If an image is returned, it must be freed with fp_img_free() after + * use. + * Performs a new scan and verify it against a previously enrolled print. * If the device is an imaging device, it can also return the image from * the scan, even when the verify fails with a RETRY code. It is legal to * call this function even on non-imaging devices, just don't expect them to * provide images. * - * \param dev the device to perform the scan. - * \param enrolled_print the print to verify against. Must have been previously - * enrolled with a device compatible to the device selected to perform the scan. - * \param img location to store the scan image. accepts NULL for no image - * storage. If an image is returned, it must be freed with fp_img_free() after - * use. - * \return negative code on error, otherwise a code from #fp_verify_result + * Returns: negative code on error, otherwise a code from #fp_verify_result */ API_EXPORTED int fp_verify_finger_img(struct fp_dev *dev, struct fp_print_data *enrolled_print, struct fp_img **img) @@ -416,7 +425,19 @@ static void identify_stop_cb(struct fp_dev *dev, void *user_data) *stopped = TRUE; } -/** \ingroup dev +/** + * fp_identify_finger_img: + * @dev: the device to perform the scan. + * @print_gallery: NULL-terminated array of pointers to the prints to + * identify against. Each one must have been previously enrolled with a device + * compatible to the device selected to perform the scan. + * @match_offset: output location to store the array index of the matched + * gallery print (if any was found). Only valid if FP_VERIFY_MATCH was + * returned. + * @img: location to store the scan image. accepts %NULL for no image + * storage. If an image is returned, it must be freed with fp_img_free() after + * use. + * Performs a new scan and attempts to identify the scanned finger against * a collection of previously enrolled fingerprints. * If the device is an imaging device, it can also return the image from @@ -435,17 +456,7 @@ static void identify_stop_cb(struct fp_dev *dev, void *user_data) * Not all devices support identification. -ENOTSUP will be returned when * this is the case. * - * \param dev the device to perform the scan. - * \param print_gallery NULL-terminated array of pointers to the prints to - * identify against. Each one must have been previously enrolled with a device - * compatible to the device selected to perform the scan. - * \param match_offset output location to store the array index of the matched - * gallery print (if any was found). Only valid if FP_VERIFY_MATCH was - * returned. - * \param img location to store the scan image. accepts NULL for no image - * storage. If an image is returned, it must be freed with fp_img_free() after - * use. - * \return negative code on error, otherwise a code from #fp_verify_result + * Returns: negative code on error, otherwise a code from #fp_verify_result */ API_EXPORTED int fp_identify_finger_img(struct fp_dev *dev, struct fp_print_data **print_gallery, size_t *match_offset, @@ -533,23 +544,26 @@ static void capture_stop_cb(struct fp_dev *dev, void *user_data) fp_dbg(""); *stopped = TRUE; } -/** \ingroup dev - * Captures an \ref img "image" from a device. The returned image is the raw - * image provided by the device, you may wish to \ref img_std "standardize" it. +/** + * fp_dev_img_capture: + * @dev: the device + * @unconditional: whether to unconditionally capture an image, or to only capture when a finger is detected + * @img: a location to return the captured image. Must be freed with + * fp_img_free() after use. * - * If set, the unconditional flag indicates that the device should + * Captures a #fp_img "image" from a device. The returned image is the raw + * image provided by the device, you may wish to [standardize](libfprint-Image-operations.html#img_std) it. + * + * If set, the @unconditional flag indicates that the device should * capture an image unconditionally, regardless of whether a finger is there * or not. If unset, this function will block until a finger is detected on * the sensor. * - * \param dev the device - * \param unconditional whether to unconditionally capture an image, or to only capture when a finger is detected - * \param img a location to return the captured image. Must be freed with - * fp_img_free() after use. - * \return 0 on success, non-zero on error. -ENOTSUP indicates that either the - * unconditional flag was set but the device does not support this, or that the + * See fp_dev_supports_imaging(). + * + * Returns: 0 on success, non-zero on error. -ENOTSUP indicates that either the + * @unconditional flag was set but the device does not support this, or that the * device does not support imaging. - * \sa fp_dev_supports_imaging() */ API_EXPORTED int fp_dev_img_capture(struct fp_dev *dev, int unconditional, struct fp_img **img) diff --git a/meson.build b/meson.build index f30732a1..a9abc3f2 100644 --- a/meson.build +++ b/meson.build @@ -101,9 +101,12 @@ endif libfprint_conf.set('API_EXPORTED', '__attribute__((visibility("default")))') configure_file(output: 'config.h', configuration: libfprint_conf) -subdir('doc') subdir('libfprint') subdir('examples') +if get_option('doc') + gnome = import('gnome') + subdir('doc') +endif pkgconfig = import('pkgconfig') pkgconfig.generate( diff --git a/meson_options.txt b/meson_options.txt index 709e0eac..ee442c3c 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -22,3 +22,7 @@ option('debug_log', description: 'Debug message logging', type: 'boolean', value: false) +option('doc', + description: 'Whether to build the API documentation', + type: 'boolean', + value: true)