(v13) set_param set a device parameter

This page applies to Harlequin v13.1r0 and later; and to Harlequin Core but not Harlequin MultiRIP

int32 set_param ( DEVICELIST *dev, DEVICEPARAM *param);

The PostScript language operator setdevparams will call this device routine. The param argument specifies the device parameter and its value in the following structure:

TEXT

  typedef struct { uint8 *paramname ;
  int32 paramnamelen ;
  int32 type ;
  union {
    int32 intval ; int32 boolval ; uint8 *strval; float floatval ;
    struct DEVICEPARAM *compobval;
  } paramval;
  int32 strvallen ;
  } DEVICEPARAM ;

The strings paramname and strval are not zero-terminated. The strings are stored in the Harlequin Core internal memory which may be re-used; therefore, if the device needs to keep referring to the string, it must copy it into its own static memory. The type field is one of the following values (defined in swdevice.h ):

TEXT

                            ParamBoolean
                            ParamInteger
                            ParamString
                            ParamFloat
                            ParamArray
                            ParamDict
                            ParamNull

These correspond to the PostScript language type of the value for one of the keys in the dictionary passed to setdevparams , except that values that are PostScript language name objects are passed to this routine as if they were strings.

In the case of ParamArray , compobval points to the array's contents (in the same form, and which may themselves be arrays or dictionaries). strvallen indicates how many elements there are.

In the case of ParamDict , compobval points to an array of DEVICEPARAM structures, which are organized in pairs, the first of each pair being the PostScript language dictionary key and the second being the corresponding value. There are strvallen such pairs.

For ParamNull , the value is ignored.

The first call to setdevparams after creating a device with devmount must set the device type. This is to prevent attempts to do anything with the device before the device routines are installed. An invalidaccess error occurs if the /DeviceType i s missing on the first call. The device_init routine of the device is called when the DeviceType parameter is set. ((v13) device_init initialize a device describes device_init .)

The routine returns a code to indicate the success or failure of setting the parameter. The following values (defined in swdevice.h ) can be returned:

TEXT

                            ParamAccepted
                            ParamTypeCheck
                            ParamRangeCheck
                            ParamConfigError
                            ParamIgnored
                            ParamError

The value ParamAccepted means that the parameter has been set successfully. This does not necessarily mean the exact value was used, or that the parameter will read back with the value just set: these things are implementation defined. ParamTypeCheck means the value was not one of the right types for the parameter of that name. ParamRangeCheck indicates that the value was unreasonable for that device parameter. ParamConfigError indicates that the value was reasonable, but not achievable with this implementation. If the parameter name is not one of those supported by this device, ParamIgnored should be returned. ParamError means that some other error occurred for example, this error might be that configuring underlying hardware failed. If ParamError is returned, last_error will be called to determine what error occurred.

The following device parameters are valid for all devices, and are not passed to the device. They are handled internally by the Harlequin Core.

Password device param

string

See the description of setdevparams in [RB3].

DeviceType device param

integer

Sets the device type pointer in the device structure to point to the device type specified by the number.

Enable device param

boolean

If set to true , permits operations on that device. An invalidaccess error is generated if the device's type has not been set yet.