API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

IXOPTS

Brew Release
Brew MP 1.0.2
See Also
Description
The IxOpts (xOpt management) API is used to manipulate configuration for a service such as IWeb. IxOpts represents a stack or list of options, which may be single- or multi-valued. IxOpts does not enforce semantics of single- or multi-valued options. Access to the options stack is dictated by the order in which the options are added.
For example:

   A list built with:
        AddOpt({OPT1, x})            ==> push {OPT1, x}
        AddOpt({OPT1, y})            ==> push {OPT1, y}
        AddOpt({OPT1, z})            ==> push {OPT1, z}
        RemoveOpt(OPT1, 0)           ==> remove 0th OPT1 (which is {OPT1, z})
        AddOpt({OPT2, b},{OPT2, a}}) ==> push {OPT2, a}, then push {OPT2, b}

   Yields answers:
        GetOpt(OPT1, 0) ==> find 0th OPT1 => {OPT1, y}
        GetOpt(OPT1, 1) ==> find 1st OPT1 => {OPT1, x}
        GetOpt(OPT1, 2) ==> find 2nd OPT1 => AEE_EFAILED
        GetOpt(OPT1, 3) ==> find 3rd OPT1 => AEE_EFAILED
        GetOpt(OPT2, 1) ==> find 1st OPT2 => {OPT2, a}

IxOpts is the base class of IWeb and IWebResp, which use IxOpts methods to communicate all kinds of stuff.

IxOpt nOptIds


The xOpt ids fall in ranges that are designed to keep the pVal data opaque while helping the service deal with copying the data if necessary.
Depending on the underlying service, the data passed as options may or may not be copied. If it is not copied, the data must stay valid as specified for the service. Check the specific service which uses IxOpts for the default copy option.
Here are the ranges and to-date defined XOPT id values and ranges:
- RESERVED range: pVals are reserved, as are ids, up to 0x0ffff, used
for control of the IxOpts, markers in internal lists

  • XOPT_RESERVED: 0
  • XOPT_RESERVED_LAST: 0x0ffff

  • XOPT_END: - no pVal, used for terminating a vector of xOpts

  • XOPT_ANY: - no pVal, matches any opt, used for enumeration

  • XOPT_REMOVED: - no pVal, means skip or ignore, is deleted

  • XOPT_COPYOPTS: - (boolean) if set to TRUE, causes the IxOpts
  • to copy current and future xOpt values.
  • Unfortunately, it's almost a one-way street, since
  • only an empty IxOpts may be changed from copy to
  • non-copy. XOPT_COPYOPTS is set to true by default.

- SZ RANGE: pVals are NULL-terminated strings, valid ids up to 0x01ffff
  • XOPT_SZ: 0x00010000
  • XOPT_SZ_LAST: 0x0001ffff

- 32-bit range: pVals 32-bit quantities, no need to (actually can't)
copy, valid ids up to 0x02ffff

  • XOPT_32BIT: 0x00020000
  • XOPT_32BIT_LAST: 0x0002ffff

- Brew MP Interface range: pVals are pointers to interfaces, which are
AddRef'd to copy valid ids up to 0x03ffff

  • XOPT_INTERFACE: 0x00030000
  • XOPT_INTERFACE_LAST: 0x0003ffff

  • One XOPT_INTERFACE is reserved for the IxOpts interface: XOPT_DEFAULTS.
  • XOPT_DEFAULTS can be used to add an IxOpt with a default set of values
  • to another IxOpt.

- Variable size range: pVals are pointers to opaque, but copyable
structures, the low 12 bits of the id specify length of the option, in bytes. Valid ids up to 0x1ffff000, spaced by 0x1000.

  • XOPT_VARIABLE: 0x10000000
  • XOPT_VARIABLE_LAST: 0x1ffff000

- Variable buffer range: pVals are pointers to opaque, but
copyable structures, the first two bytes give the length of the following data. The length is little-endian, low byte first. Valid ids up to 0x0004ffff.

  • XOPT_VARBUFFER: 0x00040000
  • XOPT_VARBUFFER_LAST: 0x0004ffff

- ASN.1 range: pVals are pointers to opaque ASN.1, but copyable
structures. The length of the object comes from the ASN.1 length of the object which starts at the second byte of the data. The first byte is the type (it doesn't matter what the type of the object is). The length is in the standard ASN.1 length format. (At present there is a 64Kb limit on the length). To derive the total length of the object, take the ASN.1 length of the object, add one for the type and then the length of the length. Note this is for DER & BER encoded objects. Note that it is a good idea to check the length and be sure it is valid before adding such options, especially if copy opts is set. If the length is wilde a malloc of a large amount of memory may be attempted and/or a copy off the end of a buffer may be attempted. Valid ids up to 0x0005ffff.
  • XOPT_ASN1: 0x00050000
  • XOPT_ASN1_LAST: 0x0005ffff

- WSZ RANGE: pVals are NULL-terminated AECHAR strings, valid ids up to
0x06ffff

  • XOPT_WSZ: 0x00060000
  • XOPT_WSZ_LAST: 0x0006ffff


Required header files:
AEEIxOpts.h