sane_control_option

This function is used to set or inquire the current value of option number n of the device represented by handle h. The manner in which the option is controlled is specified by parameter a. The possible values of this parameter are described in more detail below. The value of the option is passed through argument v. It is a pointer to the memory that holds the option value. The memory area pointed to by v must be big enough to hold the entire option value (determined by member size in the corresponding option descriptor). The only exception to this rule is that when setting the value of a string option, the string pointed to by argument v may be shorter since the backend will stop reading the option value upon encountering the first NUL terminator in the string. If argument i is not NULL, the value of *i will be set to provide details on how well the request has been met. The meaning of this argument is described in more detail below.

SANE_Status sane_control_option (SANE_Handle h, SANE_Int n,
                                 SANE_Action a, void *v,
                                 SANE_Int * i);

The way the option is affected by a call to this function is controlled by parameter a which is a value of type SANE_Action. The possible values and their meaning is described in Table 4.7.

表 4.7: Action Values (SANE_Action)

Symbol	Code	Description
SANE_ACTION_GET_VALUE	0	Get current option value.
SANE_ACTION_SET_VALUE	1	Set option value. The option value passed through argument v may be modified by the backend if the value cannot be set exactly.
SANE_ACTION_SET_AUTO	2	Turn on automatic mode. Backend or device will automatically select an appropriate value. This mode remains effective until overridden by an explicit set value request. The value of parameter v is completely ignored in this case and may be NULL.

After setting a value via an action value of SANE_ACTION_SET_VALUE, additional information on how well the request has been met is returned in *i (if i is non-NULL). The returned value is a bitset that may contain any combination of the values described in Table 4.8.

表 4.8: Additional Information Returned When Setting an Option

Symbol	Code	Description
SANE_INFO_INEXACT	1	This value is returned when setting an option value resulted in a value being selected that does not exactly match the requested value. For example, if a scanner can adjust the resolution in increments of 30dpi only, setting the resolution to 307dpi may result in an actual setting of 300dpi. When this happens, the bitset returned in *i has this member set. In addition, the option value is modified to reflect the actual (rounded) value that was used by the backend. Note that inexact values are admissible for strings as well. A backend may choose to ``round'' a string to the closest matching legal string for a constrained string value.
SANE_INFO_RELOAD_OPTIONS	2	The setting of an option may affect the value or availability of one or more other options. When this happens, the SANE backend sets this member in *i to indicate that the application should reload all options. This member may be set if and only if at least one option changed.
SANE_INFO_RELOAD_PARAMS	4	The setting of an option may affect the parameter values (see sane_get_parameters()). If setting an option affects the parameter values, this member will be set in *i. Note that this member may be set even if the parameters did not actually change. However, it is guaranteed that the parameters never change without this member being set.

This function may fail with one of the following status codes.

SANE_STATUS_UNSUPPORTED:

The operation is not supported for the specified handle and option number.

SANE_STATUS_INVAL:

The option value is not valid.

SANE_STATUS_IO_ERROR:

An error occured while communicating with the device.

SANE_STATUS_NO_MEM:

An insufficent amount of memory is available.

SANE_STATUS_ACCESS_DENIED:

Access to the option has been denied due to insufficient or invalid authentication.