UPnPStateVariable
Date: 2016-06-25

org.osgi.service.upnp

## Interface UPnPStateVariable

- All Known Subinterfaces:
    UPnPLocalStateVariable

      public interface UPnPStateVariable

  The meta-information of a UPnP state variable as declared in the device's service state table (SST).

  Method calls to interact with a device (e.g. `UPnPAction.invoke(...);`) use this class to encapsulate meta information about the input and output arguments.

  The actual values of the arguments are passed as Java objects. The mapping of types from UPnP data types to Java data types is described with the field definitions.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `TYPE_BIN_BASE64` MIME-style Base64 encoded binary BLOB.
    `static java.lang.String` | `TYPE_BIN_HEX` Hexadecimal digits representing octets.
    `static java.lang.String` | `TYPE_BOOLEAN` True or false.
    `static java.lang.String` | `TYPE_CHAR` Unicode string.
    `static java.lang.String` | `TYPE_DATE` A calendar date.
    `static java.lang.String` | `TYPE_DATETIME` A specific instant of time.
    `static java.lang.String` | `TYPE_DATETIME_TZ` A specific instant of time.
    `static java.lang.String` | `TYPE_FIXED_14_4` Same as r8 but no more than 14 digits to the left of the decimal point and no more than 4 to the right.
    `static java.lang.String` | `TYPE_FLOAT` Floating-point number.
    `static java.lang.String` | `TYPE_I1` 1 Byte int.
    `static java.lang.String` | `TYPE_I2` 2 Byte int.
    `static java.lang.String` | `TYPE_I4` 4 Byte int.
    `static java.lang.String` | `TYPE_INT` Integer number.
    `static java.lang.String` | `TYPE_NUMBER` Same as r8.
    `static java.lang.String` | `TYPE_R4` 4 Byte float.
    `static java.lang.String` | `TYPE_R8` 8 Byte float.
    `static java.lang.String` | `TYPE_STRING` Unicode string.
    `static java.lang.String` | `TYPE_TIME` An instant of time that recurs every day.
    `static java.lang.String` | `TYPE_TIME_TZ` An instant of time that recurs every day.
    `static java.lang.String` | `TYPE_UI1` Unsigned 1 `Byte` int.
    `static java.lang.String` | `TYPE_UI2` Unsigned 2 Byte int.
    `static java.lang.String` | `TYPE_UI4` Unsigned 4 Byte int.
    `static java.lang.String` | `TYPE_URI` Universal Resource Identifier.
    `static java.lang.String` | `TYPE_UUID` Universally Unique ID.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String[]` | `getAllowedValues()` Returns the allowed values, if defined.
    `java.lang.Object` | `getDefaultValue()` Returns the default value, if defined.
    `java.lang.Class` | `getJavaDataType()` Returns the Java class associated with the UPnP data type of this state variable.
    `java.lang.Number` | `getMaximum()` Returns the maximum value, if defined.
    `java.lang.Number` | `getMinimum()` Returns the minimum value, if defined.
    `java.lang.String` | `getName()` Returns the variable name.
    `java.lang.Number` | `getStep()` Returns the size of an increment operation, if defined.
    `java.lang.String` | `getUPnPDataType()` Returns the UPnP type of this state variable.
    `boolean` | `sendsEvents()` Tells if this StateVariable can be used as an event source.

- - ### Field Detail

    - #### TYPE_UI1

          static final java.lang.String TYPE_UI1

      Unsigned 1 `Byte` int.

      Mapped to an `Integer` object.

      See Also:
        Constant Field Values

    - #### TYPE_UI2

          static final java.lang.String TYPE_UI2

      Unsigned 2 Byte int.

      Mapped to `Integer` object.

      See Also:
        Constant Field Values

    - #### TYPE_UI4

          static final java.lang.String TYPE_UI4

      Unsigned 4 Byte int.

      Mapped to `Long` object.

      See Also:
        Constant Field Values

    - #### TYPE_I1

          static final java.lang.String TYPE_I1

      1 Byte int.

      Mapped to `Integer` object.

      See Also:
        Constant Field Values

    - #### TYPE_I2

          static final java.lang.String TYPE_I2

      2 Byte int.

      Mapped to `Integer` object.

      See Also:
        Constant Field Values

    - #### TYPE_I4

          static final java.lang.String TYPE_I4

      4 Byte int.

      Must be between -2147483648 and 2147483647

      Mapped to `Integer` object.

      See Also:
        Constant Field Values

    - #### TYPE_INT

          static final java.lang.String TYPE_INT

      Integer number.

      Mapped to `Integer` object.

      See Also:
        Constant Field Values

    - #### TYPE_R4

          static final java.lang.String TYPE_R4

      4 Byte float.

      Same format as float. Must be between 3.40282347E+38 to 1.17549435E-38.

      Mapped to `Float` object.

      See Also:
        Constant Field Values

    - #### TYPE_R8

          static final java.lang.String TYPE_R8

      8 Byte float.

      Same format as float. Must be between -1.79769313486232E308 and -4.94065645841247E-324 for negative values, and between 4.94065645841247E-324 and 1.79769313486232E308 for positive values, i.e., IEEE 64-bit (8-Byte) double.

      Mapped to `Double` object.

      See Also:
        Constant Field Values

    - #### TYPE_NUMBER

          static final java.lang.String TYPE_NUMBER

      Same as r8.

      Mapped to `Double` object.

      See Also:
        Constant Field Values

    - #### TYPE_FIXED_14_4

          static final java.lang.String TYPE_FIXED_14_4

      Same as r8 but no more than 14 digits to the left of the decimal point and no more than 4 to the right.

      Mapped to `Double` object.

      See Also:
        Constant Field Values

    - #### TYPE_FLOAT

          static final java.lang.String TYPE_FLOAT

      Floating-point number.

      Mantissa (left of the decimal) and/or exponent may have a leading sign. Mantissa and/or exponent may have leading zeros. Decimal character in mantissa is a period, i.e., whole digits in mantissa separated from fractional digits by period. Mantissa separated from exponent by E. (No currency symbol.) (No grouping of digits in the mantissa, e.g., no commas.)

      Mapped to `Float` object.

      See Also:
        Constant Field Values

    - #### TYPE_CHAR

          static final java.lang.String TYPE_CHAR

      Unicode string.

      One character long.

      Mapped to `Character` object.

      See Also:
        Constant Field Values

    - #### TYPE_STRING

          static final java.lang.String TYPE_STRING

      Unicode string.

      No limit on length.

      Mapped to `String` object.

      See Also:
        Constant Field Values

    - #### TYPE_DATE

          static final java.lang.String TYPE_DATE

      A calendar date.

      Date in a subset of ISO 8601 format without time data.

      See http://www.w3.org/TR/ xmlschema-2/#date .

      Mapped to `java.util.Date` object. Always 00:00 hours.

      See Also:
        Constant Field Values

    - #### TYPE_DATETIME

          static final java.lang.String TYPE_DATETIME

      A specific instant of time.

      Date in ISO 8601 format with optional time but no time zone.

      See http://www.w3.org /TR/xmlschema-2/#dateTime .

      Mapped to `java.util.Date` object using default time zone.

      See Also:
        Constant Field Values

    - #### TYPE_DATETIME_TZ

          static final java.lang.String TYPE_DATETIME_TZ

      A specific instant of time.

      Date in ISO 8601 format with optional time and optional time zone.

      See http://www.w3.org /TR/xmlschema-2/#dateTime .

      Mapped to `java.util.Date` object adjusted to default time zone.

      See Also:
        Constant Field Values

    - #### TYPE_TIME

          static final java.lang.String TYPE_TIME

      An instant of time that recurs every day.

      Time in a subset of ISO 8601 format with no date and no time zone.

      See http://www.w3.org /TR/xmlschema-2/#time .

      Mapped to `Long`. Converted to milliseconds since midnight.

      See Also:
        Constant Field Values

    - #### TYPE_TIME_TZ

          static final java.lang.String TYPE_TIME_TZ

      An instant of time that recurs every day.

      Time in a subset of ISO 8601 format with optional time zone but no date.

      See http://www.w3.org /TR/xmlschema-2/#time .

      Mapped to `Long` object. Converted to milliseconds since midnight and adjusted to default time zone, wrapping at 0 and 24*60*60*1000.

      See Also:
        Constant Field Values

    - #### TYPE_BOOLEAN

          static final java.lang.String TYPE_BOOLEAN

      True or false.

      Mapped to `Boolean` object.

      See Also:
        Constant Field Values

    - #### TYPE_BIN_BASE64

          static final java.lang.String TYPE_BIN_BASE64

      MIME-style Base64 encoded binary BLOB.

      Takes 3 Bytes, splits them into 4 parts, and maps each 6 bit piece to an octet. (3 octets are encoded as 4.) No limit on size.

      Mapped to `byte[]` object. The Java byte array will hold the decoded content of the BLOB.

      See Also:
        Constant Field Values

    - #### TYPE_BIN_HEX

          static final java.lang.String TYPE_BIN_HEX

      Hexadecimal digits representing octets.

      Treats each nibble as a hex digit and encodes as a separate Byte. (1 octet is encoded as 2.) No limit on size.

      Mapped to `byte[]` object. The Java byte array will hold the decoded content of the BLOB.

      See Also:
        Constant Field Values

    - #### TYPE_URI

          static final java.lang.String TYPE_URI

      Universal Resource Identifier.

      Mapped to `String` object.

      See Also:
        Constant Field Values

    - #### TYPE_UUID

          static final java.lang.String TYPE_UUID

      Universally Unique ID.

      Hexadecimal digits representing octets. Optional embedded hyphens are ignored.

      Mapped to `String` object.

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getName

          java.lang.String getName()

      Returns the variable name.
      - All standard variables defined by a UPnP Forum working committee must not begin with `X_` nor `A_`.
      - All non-standard variables specified by a UPnP vendor and added to a standard service must begin with `X_`.

      This method must continue to return the state variable name after the UPnP state variable has been removed from the network.

      Returns:
        Name of state variable. Must not contain a hyphen character nor a hash character. Should be < 32 characters.

    - #### getJavaDataType

          java.lang.Class getJavaDataType()

      Returns the Java class associated with the UPnP data type of this state variable.

      Mapping between the UPnP data types and Java classes is performed according to the schema mentioned above.

            Integer              ui1, ui2, i1, i2, i4, int
            Long                 ui4, time, time.tz
            Float                r4, float
            Double               r8, number, fixed.14.4
            Character            char
            String               string, uri, uuid
            Date                 date, dateTime, dateTime.tz
            Boolean              boolean
            byte[]               bin.base64, bin.hex

      This method must continue to return the state variable java type after the UPnP state variable has been removed from the network.

      Returns:
        A class object corresponding to the Java type of this argument.

    - #### getUPnPDataType

          java.lang.String getUPnPDataType()

      Returns the UPnP type of this state variable. Valid types are defined as constants.

      This method must continue to return the state variable UPnP data type after the UPnP state variable has been removed from the network.

      Returns:
        The UPnP data type of this state variable, as defined in above constants.

    - #### getDefaultValue

          java.lang.Object getDefaultValue()

      Returns the default value, if defined.

      This method must continue to return the state variable default value after the UPnP state variable has been removed from the network.

      Returns:
        The default value or `null` if not defined. The type of the returned object can be determined by `getJavaDataType`.

    - #### getAllowedValues

          java.lang.String[] getAllowedValues()

      Returns the allowed values, if defined. Allowed values can be defined only for String types.

      This method must continue to return the state variable allowed values after the UPnP state variable has been removed from the network.

      Returns:
        The allowed values or `null` if not defined. Should be less than 32 characters.

    - #### getMinimum

          java.lang.Number getMinimum()

      Returns the minimum value, if defined. Minimum values can only be defined for numeric types.

      This method must continue to return the state variable minimum value after the UPnP state variable has been removed from the network.

      Returns:
        The minimum value or `null` if not defined.

    - #### getMaximum

          java.lang.Number getMaximum()

      Returns the maximum value, if defined. Maximum values can only be defined for numeric types.

      This method must continue to return the state variable maximum value after the UPnP state variable has been removed from the network.

      Returns:
        The maximum value or `null` if not defined.

    - #### getStep

          java.lang.Number getStep()

      Returns the size of an increment operation, if defined. Step sizes can be defined only for numeric types.

      This method must continue to return the step size after the UPnP state variable has been removed from the network.

      Returns:
        The increment size or null if not defined.

    - #### sendsEvents

          boolean sendsEvents()

      Tells if this StateVariable can be used as an event source. If the StateVariable is eventable, an event listener service can be registered to be notified when changes to the variable appear.

      This method must continue to return the correct value after the UPnP state variable has been removed from the network.

      Returns:
        `true` if the `StateVariable` generates events, `false` otherwise.