sane_init

This function must be called before any other SANE function can be called. The behavior of a SANE backend is undefined if this function is not called first. The version code of the backend is returned in the value pointed to by version_code. If that pointer is NULL, no version code is returned. Argument authorize is either a pointer to a function that is invoked when the backend requires authentication for a specific resource or NULL if the frontend does not support authentication.

SANE_Status sane_init (SANE_Int * version_code,
                       SANE_Authorization_Callback authorize);

The authorization function may be called by a backend in response to any of the following calls:

sane_open, sane_control_option, sane_start

If a backend was initialized without authorization function, then authorization requests that cannot be handled by the backend itself will fail automatically and the user may be prevented from accessing protected resources. Backends are encouraged to implement means of authentication that do not require user assistance. E.g., on a multi-user system that authenticates users through a login process a backend could automatically lookup the apporpriate password based on resource- and user-name.

The authentication function type has the following declaration:

#define SANE_MAX_USERNAME_LEN   128
#define SANE_MAX_PASSWORD_LEN   128

typedef void (*SANE_Authorization_Callback)
    (SANE_String_Const resource,
     SANE_Char username[SANE_MAX_USERNAME_LEN],
     SANE_Char password[SANE_MAX_PASSWORD_LEN]);

Three arguments are passed to the authorization function: resource is a string specifying the name of the resource that requires authorization. A frontend should use this string to build a user-prompt requesting a username and a password. The username and password arguments are (pointers to) an array of SANE_MAX_USERNAME_LEN and SANE_MAX_PASSWORD_LEN characters, respectively. The authorization call should place the entered username and password in these arrays. The returned strings must be ASCII-NUL terminated.