kopia lustrzana https://gitlab.com/sane-project/backends
Added, fixed and updated documentation for sanei using doxygen.
Henning Meier-Geinitz <henning@meier-geinitz.de>DEVEL_2_0_BRANCH-1
Henning Geinitz
rodzic
8ecebeefc5
commit
6f13df5932
10
ChangeLog
10
ChangeLog
|
|
@ -1,3 +1,13 @@
|
|||
2002-02-15 Henning Meier-Geinitz <henning@meier-geinitz.de>
|
||||
|
||||
* include/sane/sanei.h include/sane/sanei_ab306.h
|
||||
include/sane/sanei_auth.h include/sane/sanei_backend.h
|
||||
include/sane/sanei_codec_ascii.h include/sane/sanei_codec_bin.h
|
||||
include/sane/sanei_config.h include/sane/sanei_debug.h
|
||||
include/sane/sanei_lm983x.h include/sane/sanei_thread.h
|
||||
include/sane/sanei_usb.h: Added, fixed and updated documentation
|
||||
for sanei using doxygen.
|
||||
|
||||
2002-02-15 Stéphane Voltz <svoltz@wanadoo.fr>
|
||||
|
||||
* backend/umax_pp_low.c backend/umax_pp_low.h backend/umax_pp_mid.h
|
||||
|
|
|
|||
|
|
@ -18,13 +18,15 @@
|
|||
*/
|
||||
|
||||
/** @file sanei.h
|
||||
* Convenience macros and function declarations for backends
|
||||
* Convenience macros and function declarations for backends
|
||||
* @sa sanei_backend.h sanei_thread.h
|
||||
*/
|
||||
|
||||
/* Doxygen documentation */
|
||||
|
||||
/** @mainpage SANEI (SANE internal routines) documentation
|
||||
*
|
||||
* @image html ../sane-logo2.jpg
|
||||
* @section intro Introduction
|
||||
*
|
||||
* The header files in the include/sane/ directory named sanei_*.h provide
|
||||
|
|
@ -63,29 +65,21 @@
|
|||
|
||||
#include <sane/sane.h>
|
||||
|
||||
/* A few convenience macros: */
|
||||
|
||||
/** @name Public macros and functions
|
||||
* @{
|
||||
*/
|
||||
/** @def STRINGIFY(x)
|
||||
* Turn parameter into string.
|
||||
*
|
||||
*/
|
||||
#define STRINGIFY1(x) #x
|
||||
#define STRINGIFY(x) STRINGIFY1(x)
|
||||
|
||||
/** @def PASTE(x,y)
|
||||
* Concatenate parameters.
|
||||
*
|
||||
*/
|
||||
#define PASTE1(x,y) x##y
|
||||
#define PASTE(x,y) PASTE1(x,y)
|
||||
|
||||
/** @def NELEMS(a)
|
||||
* Return number of elements of an array.
|
||||
*
|
||||
*/
|
||||
#define NELEMS(a) ((int)(sizeof (a) / sizeof (a[0])))
|
||||
|
||||
/**
|
||||
/** @fn extern SANE_Status sanei_constrain_value (const SANE_Option_Descriptor * opt, void * value, SANE_Word * info);
|
||||
* Check the constraints of a SANE option and adjust its value if necessary.
|
||||
*
|
||||
* Depending on the type of the option and constraint, value is modified
|
||||
|
|
@ -100,6 +94,33 @@
|
|||
* - SANE_STATUS_INVAL - if the function wasn't able to fit value into the
|
||||
* constraint or any other error occured
|
||||
*/
|
||||
/* @} */
|
||||
|
||||
/** @name Private macros
|
||||
* @{
|
||||
*/
|
||||
/** @def STRINGIFY1(x)
|
||||
* Internal use only.
|
||||
*/
|
||||
/** @def PASTE1(x,y)
|
||||
* Internal use only.
|
||||
*/
|
||||
/* @} */
|
||||
|
||||
/* A few convenience macros: */
|
||||
/** @hideinitializer */
|
||||
#define NELEMS(a) ((int)(sizeof (a) / sizeof (a[0])))
|
||||
|
||||
/** @hideinitializer */
|
||||
#define STRINGIFY1(x) #x
|
||||
/** @hideinitializer */
|
||||
#define STRINGIFY(x) STRINGIFY1(x)
|
||||
|
||||
/** @hideinitializer */
|
||||
#define PASTE1(x,y) x##y
|
||||
/** @hideinitializer */
|
||||
#define PASTE(x,y) PASTE1(x,y)
|
||||
|
||||
extern SANE_Status sanei_constrain_value (const SANE_Option_Descriptor * opt,
|
||||
void * value, SANE_Word * info);
|
||||
|
||||
|
|
|
|||
|
|
@ -51,6 +51,8 @@
|
|||
*
|
||||
* Depending on the operating system it may be necessary to run this code as
|
||||
* root.
|
||||
*
|
||||
* @sa sanei_pio.h sanei_scsi.h sanei_usb.h
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -37,45 +37,58 @@
|
|||
If you write modifications of your own for SANE, it is your choice
|
||||
whether to permit this exception to apply to your modifications.
|
||||
If you do not wish that, delete this exception notice.
|
||||
*/
|
||||
|
||||
This file implements an interface for user authorization using MD5 digest */
|
||||
/** @file sanei_auth.h
|
||||
* Interface for authorization of resources
|
||||
*
|
||||
* This file implements an interface for user authorization. The authorization
|
||||
* call is forwarded to the frontend which asks for a username and password.
|
||||
* An MD5 digest is used if supported by the frontend.
|
||||
*
|
||||
* @sa sanei.h sanei_backend.h
|
||||
*/
|
||||
|
||||
#ifndef sanei_auth_h
|
||||
#define sanei_auth_h
|
||||
|
||||
#include "../include/sane/sane.h"
|
||||
|
||||
/* this function needs the name of the resource to authorize, the name
|
||||
* of the backend and the auth_callback. It looks for the file:
|
||||
* SANE_CONFIG_DIR/backend.users
|
||||
/** Check authorization for a resource
|
||||
*
|
||||
* if this file doesn't exist, sanei_authorize always returns SANE_STATUS_GOOD
|
||||
* This function looks for the file SANE_CONFIG_DIR/backend.users.
|
||||
* If this file doesn't exist, sanei_authorize always returns SANE_STATUS_GOOD.
|
||||
* The file backend.users contains a list of usernames, passwords, and
|
||||
* resources:
|
||||
*
|
||||
* the file backend.users contains a list of resource usernames and passwords
|
||||
* username:password:resource
|
||||
* username:password:resource
|
||||
*
|
||||
* resource:username:password
|
||||
* resource:username:password
|
||||
*
|
||||
* if the requested resource isn't listed in this file, sanei_authorize
|
||||
* return SANE_SATUS_GOOD
|
||||
*
|
||||
* in all other cases, sanei_authorize sends a challenge to the frontend
|
||||
* of the form
|
||||
* If the requested resource isn't listed in this file, sanei_authorize
|
||||
* return SANE_SATUS_GOOD. In all other cases, sanei_authorize sends a
|
||||
* challenge to the frontend of the form
|
||||
*
|
||||
* resource$MD5$randomstring
|
||||
*
|
||||
* where randomstring consists of the PID, the time, and some random characters
|
||||
*
|
||||
* it accepts two forms of answers
|
||||
* where randomstring consists of the PID, the time, and some random
|
||||
* characters. It accepts two forms of answers
|
||||
*
|
||||
* std: username:password
|
||||
* md5: username:$MD5$m5digest
|
||||
*
|
||||
* where md5digest is md5(randomstring password)
|
||||
* where md5digest is md5(randomstring password).
|
||||
*
|
||||
* if this resource/username/password triple is listed in backend.users
|
||||
* If this username/password/resource triple is listed in backend.users
|
||||
* sanei_authorize returns SANE_STATUS_GOOD, in all other cases it returns
|
||||
* SANE_STATUS_ACCESS_DENIED
|
||||
* SANE_STATUS_ACCESS_DENIED.
|
||||
*
|
||||
* @param resource resource to authorize
|
||||
* @param backend backend name
|
||||
* @param authorize auth callback
|
||||
*
|
||||
* @return
|
||||
* - SANE_STATUS_GOOD - access is granted
|
||||
* - SANE_STATUS_ACCESS_DENIED - access is denied
|
||||
*/
|
||||
|
||||
SANE_Status
|
||||
|
|
|
|||
|
|
@ -1,3 +1,17 @@
|
|||
/** @file sanei_backend.h
|
||||
* Compatibility header file for backends
|
||||
*
|
||||
* This file provides some defines for macros missing on some platforms.
|
||||
* It also has the SANE API entry points. sanei_backend.h muste be included
|
||||
* by every backend.
|
||||
*
|
||||
* @sa sanei.h sanei_thread.h
|
||||
*/
|
||||
|
||||
/** @name Compatibility macros
|
||||
* @{
|
||||
*/
|
||||
|
||||
#include <sane/sanei_debug.h>
|
||||
|
||||
#ifdef HAVE_SYS_HW_H
|
||||
|
|
@ -73,9 +87,12 @@
|
|||
# define SIG_UNBLOCK 2
|
||||
# define SIG_SETMASK 3
|
||||
#endif /* !HAVE_SIGPROCMASK */
|
||||
/* @} */
|
||||
|
||||
/* Declare the entry points: */
|
||||
|
||||
/** @name Declaration of entry points:
|
||||
* @{
|
||||
*/
|
||||
extern SANE_Status ENTRY(init) (SANE_Int *, SANE_Auth_Callback);
|
||||
extern SANE_Status ENTRY(get_devices) (const SANE_Device ***, SANE_Bool);
|
||||
extern SANE_Status ENTRY(open) (SANE_String_Const, SANE_Handle *);
|
||||
|
|
@ -110,11 +127,14 @@ extern void ENTRY(exit) (void);
|
|||
#define sane_close(a) ENTRY(close) (a)
|
||||
#define sane_exit(a) ENTRY(exit) (a)
|
||||
#endif /* STUBS */
|
||||
/* @} */
|
||||
|
||||
/* Internationalization for SANE backends
|
||||
Add SANE_I18N() to all texts that can be translated.
|
||||
E.g. out_txt = SANE_I18N("Hello"); */
|
||||
|
||||
/** @name Internationalization for SANE backends
|
||||
* Add SANE_I18N() to all texts that can be translated.
|
||||
* E.g. out_txt = SANE_I18N("Hello");
|
||||
* @{
|
||||
*/
|
||||
#ifndef SANE_I18N
|
||||
#define SANE_I18N(text) text
|
||||
#endif
|
||||
/* @} */
|
||||
|
|
|
|||
|
|
@ -15,12 +15,27 @@
|
|||
You should have received a copy of the GNU General Public License
|
||||
along with sane; see the file COPYING. If not, write to the Free
|
||||
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
||||
*/
|
||||
|
||||
This file declares SANE application interface. See the SANE
|
||||
standard for a detailed explanation of the interface. */
|
||||
/** @file sanei_codec_ascii.h
|
||||
* ASCII codec for network and file transmissions
|
||||
*
|
||||
* Instead translating data to a byte stream this codec uses ASCII hex numbers.
|
||||
* Therefore it can be used for streams that are not 8-bit clean or which can
|
||||
* only use printable characters. It's currently used for saving/restoring
|
||||
* data to/from disk.
|
||||
*
|
||||
* @sa sanei_codec_bin.h sanei_net.h sanei_wire.h
|
||||
*/
|
||||
#ifndef sanei_codec_ascii_h
|
||||
#define sanei_codec_ascii_h
|
||||
|
||||
/** Initialize the ascii codec
|
||||
*
|
||||
* Set the i/o functions of the Wire to those of the ASCII codec.
|
||||
*
|
||||
* @param w Wire
|
||||
*/
|
||||
extern void sanei_codec_ascii_init (Wire *w);
|
||||
|
||||
#endif /* sanei_codec_ascii_h */
|
||||
|
|
|
|||
|
|
@ -15,12 +15,25 @@
|
|||
You should have received a copy of the GNU General Public License
|
||||
along with sane; see the file COPYING. If not, write to the Free
|
||||
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
||||
*/
|
||||
/** @file sanei_codec_bin.h
|
||||
* Binary codec for network transmissions
|
||||
*
|
||||
* Transtale data to a byte stream while taking byte order problems into
|
||||
* account. This codec is currently used for saned and the network backend.
|
||||
*
|
||||
* @sa sanei_codec_ascii.h sanei_net.h sanei_wire.h
|
||||
*/
|
||||
|
||||
This file declares SANE application interface. See the SANE
|
||||
standard for a detailed explanation of the interface. */
|
||||
#ifndef sanei_codec_bin_h
|
||||
#define sanei_codec_bin_h
|
||||
|
||||
/** Initialize the binary codec
|
||||
*
|
||||
* Set the i/o functions of the Wire to those of the binary codec.
|
||||
*
|
||||
* @param w Wire
|
||||
*/
|
||||
extern void sanei_codec_bin_init (Wire *w);
|
||||
|
||||
#endif /* sanei_codec_bin_h */
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@
|
|||
*/
|
||||
|
||||
/** @file sanei_config.h
|
||||
* This file provides generic configuration support.
|
||||
* Generic configuration support.
|
||||
*
|
||||
* Use the functions of this header file if you want to read and analyze
|
||||
* configuration files.
|
||||
|
|
@ -77,7 +77,7 @@ extern FILE *sanei_config_open (const char *name);
|
|||
*/
|
||||
extern char *sanei_config_read (char *str, int n, FILE *stream);
|
||||
|
||||
/** Removes all whitespace from the beginning of a string.
|
||||
/** Remove all whitespace from the beginning of a string.
|
||||
*
|
||||
* @param str string
|
||||
*
|
||||
|
|
@ -87,7 +87,7 @@ extern char *sanei_config_read (char *str, int n, FILE *stream);
|
|||
extern const char *sanei_config_skip_whitespace (const char *str);
|
||||
|
||||
|
||||
/** Scans a string constant from a line of text and returns a malloced copy
|
||||
/** Scan a string constant from a line of text and return a malloced copy
|
||||
* of it.
|
||||
*
|
||||
* It's the responsibility of the caller to free the returned string constant
|
||||
|
|
@ -122,6 +122,6 @@ extern const char *sanei_config_get_string (const char *str,
|
|||
*/
|
||||
extern void sanei_config_attach_matching_devices (const char *name,
|
||||
SANE_Status (*attach)
|
||||
(const char *dev));
|
||||
(const char *dev));
|
||||
|
||||
#endif /* sanei_config_h */
|
||||
|
|
|
|||
|
|
@ -1,28 +1,95 @@
|
|||
/** @file sanei_debug.h
|
||||
* Support for printing debug messages.
|
||||
*
|
||||
* Use the functions of this header file to print debug or warning messages.
|
||||
*/
|
||||
|
||||
#ifndef _SANEI_DEBUG_H
|
||||
#define _SANEI_DEBUG_H
|
||||
|
||||
#include <sane/sanei.h>
|
||||
|
||||
/* this header file defines:
|
||||
/** @name Public macros
|
||||
* These macros can be used in backends and other SANE-related
|
||||
* code.
|
||||
*
|
||||
* DBG_INIT() - should be called before any other debug function
|
||||
* DBG(level, fmt, ...) - prints a message at debug level `level' or higher
|
||||
* using a printf-like function
|
||||
* IF_DBG(x) - expands to x if debug support is enabled at
|
||||
* compile-time, if NDEBUG is defined at compile-time
|
||||
* this macro expands to nothing
|
||||
* Before including sanei_debug.h, the following macros must be set:
|
||||
*
|
||||
* ENTRY(name) - expands to sane_BACKEND_NAME_name
|
||||
*
|
||||
* before you include sanei_debug.h, you'll have to define
|
||||
*
|
||||
* BACKEND_NAME - the name of your backend without double-quotes
|
||||
* STUBS - if this is defined, nothing will happen
|
||||
* DEBUG_DECLARE_ONLY - generate prototypes instead of functions
|
||||
* DEBUG_NOT_STATIC - doesn't generate static functions
|
||||
* - BACKEND_NAME - The name of your backend without double-quotes (must be set in any case)
|
||||
* - STUBS - If this is defined, no macros will be included. Used in
|
||||
* backends consisting of more than one .c file.
|
||||
* - DEBUG_DECLARE_ONLY - Generates prototypes instead of functions. Used in
|
||||
* backends consisting of more than one .c file.
|
||||
* - DEBUG_NOT_STATIC - Doesn't generate static functions. Used in header files if
|
||||
* they are include in more than one .c file.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** @def DBG_INIT()
|
||||
* Initialize sanei_debug.
|
||||
*
|
||||
* Call this function before you use any DBG function.
|
||||
*/
|
||||
|
||||
/** @def DBG(level, fmt, ...)
|
||||
* Print a message at debug level `level' or higher using a printf-like
|
||||
* function. Example: DBG(1, "sane_open: opening fd \%d\\n", fd).
|
||||
*
|
||||
* @param level debug level
|
||||
* @param fmt format (see man 3 printf for details)
|
||||
* @param ... additional arguments
|
||||
*/
|
||||
|
||||
/** @def IF_DBG(x)
|
||||
* Compile code only if debugging is enabled.
|
||||
*
|
||||
* Expands to x if debug support is enabled at compile-time. If NDEBUG is
|
||||
* defined at compile-time this macro expands to nothing.
|
||||
*
|
||||
* @param x code to expand when debugging is enabled
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def DBG_LEVEL
|
||||
* Current debug level.
|
||||
*
|
||||
* You can only read this "variable".
|
||||
*/
|
||||
|
||||
/** @def ENTRY(name)
|
||||
* Expands to sane_BACKEND_NAME_name.
|
||||
*
|
||||
* Example: ENTRY(init) in mustek.c will expand to sane_mustek_init.
|
||||
*/
|
||||
|
||||
/* @} */
|
||||
|
||||
/** @name Internal macros and functions
|
||||
* Do not use in your own code.
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** @def DBG_LOCAL
|
||||
* Do not use in backends directly.
|
||||
*
|
||||
* Internal wrapper for printing function.
|
||||
*/
|
||||
|
||||
/** @fn extern void sanei_init_debug (const char * backend, int * debug_level_var);
|
||||
* Do not use in backends directly.
|
||||
*
|
||||
* Actual init function.
|
||||
*/
|
||||
|
||||
/** @fn extern void sanei_debug_msg (int level, int max_level, const char *be, const char *fmt, va_list ap);
|
||||
* Do not use in backends directly.
|
||||
*
|
||||
* Actual printing function.
|
||||
*/
|
||||
/* @} */
|
||||
|
||||
/** @hideinitializer*/
|
||||
#define ENTRY(name) PASTE(PASTE(PASTE(sane_,BACKEND_NAME),_),name)
|
||||
|
||||
#ifdef NDEBUG
|
||||
|
|
@ -36,6 +103,7 @@ extern void sanei_debug_ndebug (int level, const char *msg, ...);
|
|||
|
||||
#else /* !NDEBUG */
|
||||
|
||||
/** @hideinitializer*/
|
||||
# define DBG_LEVEL PASTE(sanei_debug_,BACKEND_NAME)
|
||||
|
||||
# if defined(BACKEND_NAME) && !defined(STUBS)
|
||||
|
|
@ -46,9 +114,11 @@ int DBG_LEVEL = 0;
|
|||
# endif /* DEBUG_DECLARE_ONLY */
|
||||
# endif /* BACKEND_NAME && !STUBS */
|
||||
|
||||
/** @hideinitializer*/
|
||||
# define DBG_INIT() \
|
||||
sanei_init_debug (STRINGIFY(BACKEND_NAME), &DBG_LEVEL)
|
||||
|
||||
/** @hideinitializer*/
|
||||
# define DBG_LOCAL PASTE(DBG_LEVEL,_call)
|
||||
|
||||
|
||||
|
|
@ -93,10 +163,12 @@ DBG_LOCAL (int level, const char *msg, ...)
|
|||
|
||||
# endif /* !STUBS */
|
||||
|
||||
/** @hideinitializer*/
|
||||
# define DBG DBG_LOCAL
|
||||
|
||||
extern void sanei_init_debug (const char * backend, int * debug_level_var);
|
||||
|
||||
/** @hideinitializer*/
|
||||
# define IF_DBG(x) x
|
||||
|
||||
#endif /* NDEBUG */
|
||||
|
|
|
|||
|
|
@ -48,6 +48,8 @@
|
|||
*
|
||||
* The National Semiconductor LM9831, LM9832, and LM9833 chips are used in
|
||||
* many USB scanners. Examples include Plustek and Mustek devices.
|
||||
*
|
||||
* @sa sanei_usb.h
|
||||
*/
|
||||
|
||||
#ifndef sanei_lm983x_h
|
||||
|
|
|
|||
|
|
@ -31,6 +31,8 @@
|
|||
* The preprocessor is used for routing process-related function to OS/2
|
||||
* threaded code: in this way, Unix backends requires only minimal code
|
||||
* changes.
|
||||
*
|
||||
* @sa sanei.h sanei_backend.h
|
||||
*/
|
||||
|
||||
|
||||
|
|
@ -38,6 +40,9 @@
|
|||
#define sanei_thread_h
|
||||
#include "../include/sane/config.h"
|
||||
|
||||
/** @name Internal functions
|
||||
* @{
|
||||
*/
|
||||
/** <b>Do not use in backends</b>
|
||||
*
|
||||
* Wrapper for @c fork.
|
||||
|
|
@ -61,6 +66,7 @@ extern int sanei_thread_waitpid( int pid, int *stat_loc, int options);
|
|||
* Wrapper for @c wait.
|
||||
*/
|
||||
extern int sanei_thread_wait( int *stat_loc);
|
||||
/* @} */
|
||||
|
||||
/** Reader process function.
|
||||
*
|
||||
|
|
|
|||
|
|
@ -25,9 +25,9 @@
|
|||
* drivers also work. However, detection and control messages aren't
|
||||
* supported on these platforms.
|
||||
*
|
||||
* See <a
|
||||
* @sa sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h, sanei_scsi.h, and <a
|
||||
* href="http://www.mostang.com/sane/man/sane-usb.5.html">man sane-usb(5)</a>
|
||||
* for user-oriented documentation.
|
||||
* for user-oriented documentation
|
||||
*/
|
||||
|
||||
#ifndef sanei_usb_h
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue