Enumerations are generally useful for the declaration of named integer-valued constants, also called enumeration constants.
11.3.1 Symbolic Encoding of Enumeration Constants
The gSOAP stub and skeleton compiler encodes the constants of enumeration-typed variables in symbolic form using the names of the constants when possible to comply to SOAP’s XML schema enumeration encoding style. Consider for example the following enumeration of weekdays:
enum weekday{Mon, Tue, Wed, Thu, Fri, Sat, Sun};
The enumeration-constant Mon, for example, is encoded as
<weekday xsi:type="weekday">Mon</weekday>
The value of the xsi:type attribute is the enumeration-type identifier’s name. If the element is independent as in the example above, the element name is the enumeration-type identifier’s name. The encoding of complex types such as enumerations requires a reference to an XML schema through the use of a namespace prefix. The namespace prefix can be specified as part of the
enumeration-type identifier’s name, with the usual namespace prefix conventions for identifiers. This can be used to explicitly specify the encoding style. For example:
enum ns1 weekday{Mon, Tue, Wed, Thu, Fri, Sat, Sun};
The enumeration-constant Sat, for example, is encoded as:
<ns1:weekday xsi:type="ns1:weekday">Sat</ns1:weekday>
The corresponding XML schema for this enumeration data type would be:
<xsd:element name="weekday" type="tns:weekday"/> <xsd:simpleType name="weekday"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="Mon"/> <xsd:enumeration value="Tue"/> <xsd:enumeration value="Wed"/> <xsd:enumeration value="Thu"/> <xsd:enumeration value="Fri"/> <xsd:enumeration value="Sat"/> <xsd:enumeration value="Sun"/> </xsd:restriction> </xsd:simpleType>
11.3.2 Encoding of Enumeration Constants
If the value of an enumeration-typed variable has no corresponding named constant, the value is encoded as a signed integer literal. For example, the following declaration of aworkdayenumeration type lacks named constants for Saturday and Sunday:
enum ns1 workday{Mon, Tue, Wed, Thu, Fri};
If the constant5(Saturday) or6(Sunday) is assigned to a variable of theworkdayenumeration type, the variable will be encoded with the integer literals5 and6, respectively. For example:
<ns1:workday xsi:type="ns1:workday">5</ns1:workday>
Since this is legal in C++ and SOAP allows enumeration constants to be integer literals, this method ensures that non-symbolic enumeration constants are correctly communicated to another party if the other party accepts literal enumeration constants (as with the gSOAP stub and skeleton compiler).
Both symbolic and literal enumeration constants can be decoded.
To enforce the literal enumeration constant encoding and to get the literal constants in the WSDL file, use the following trick:
enum ns1 nums{ 1 = 1, 2 = 2, 3 = 3 };
The difference with an enumeration type without a list of values and the enumeration type above is that the enumeration constants will appear in the WSDL service description.
11.3.3 Initialized Enumeration Constants
The gSOAP compiler supports the initialization of enumeration constants, as in:
enum ns1 relation{LESS = -1, EQUAL = 0, GREATER = 1};
The symbolic names LESS, EQUAL, and GREATER will appear in the SOAP payload for the encoding of the ns1 relationenumeration values -1,0, and 1, respectively.
11.3.4 How to “Reuse” Symbolic Enumeration Constants
A well-known deficiency of C and C++ enumeration types is the lack of support for the reuse of symbolic names by multiple enumerations. That is, the names of all the symbolic constants defined by an enumeration cannot be reused by another enumeration. To force encoding of the same symbolic name by different enumerations, the identifier of the symbolic name can end in an underscore ( ) or any number of underscores to distinguish it from other symbolic names in C++. This guarantees that the SOAP encoding will use the same name, while the symbolic names can be distinguished in C++. Effectively, the underscores are removed from a symbolic name prior to encoding.
Consider for example:
enum ns1 workday{Mon, Tue, Wed, Thu, Fri};
enum ns1 weekday{Mon , Tue , Wed , Thu , Fri , Sat , Sun };
which will result in the encoding of the constants of enum ns1 weekdaywithout the underscore, for example asMon.
Caution: The following declaration:
enum ns1 workday{Mon, Tue, Wed, Thu, Fri}; enum ns1 weekday{Sat = 5, Sun = 6};
will not properly encode theweekdayenumeration, because it lacks the named constants forworkday
in its enumeration list.
11.3.5 Boolean Enumeration Type Encoding and Decoding for C Compilers
When a pure C compiler is used to create SOAP clients and services, the bool type may not be supported by the compiler and in that case an enumeration type should be used. The C enumeration-type encoding adopted by the gSOAP stub and skeleton compiler can be used to encode boolean values according to the SOAP encoding style. The namespace prefix can be specified with the usual namespace prefix convention for identifiers to explicitly specify the encoding style. For example, the built-inbooleanXML schema type supports the mathematical concept of binary-
valued logic. The boolean XML schema encoding style can be specified by using the xsd prefix. For example:
enum xsd boolean{false , true };
<xsd:boolean xsi:type="xsd:boolean">false</xsd:boolean>
Peculiar of the SOAP boolean type encoding is that it only defines the values 0 and 1, while
the built-in XML schema boolean type also defines thefalseand truesymbolic constants as valid values. The following example declaration of an enumeration type lacks named constants altogether to force encoding of the enumeration values as literal constants:
enum SOAP ENC boolean{};
The value 0, for example, is encoded with an integer literal:
<SOAP-ENC:boolean xsi:type="SOAP-ENC:boolean">0<SOAP-ENC:boolean>
11.3.6 Bitmask Enumeration Encoding and Decoding
A bitmask is an enumeration of flags such as declared with C#’s [Flags]enumannotation. gSOAP supports bitmask encoding and decoding for interoperability. However, bitmask types are not standardized with SOAP RPC.
A special syntactic convention is used in the header file input to the gSOAP compiler to indicate the use of bitmasks with an asterisk:
enum * name{ enum-constant, enum-constant, ... };
The gSOAP compiler will encode the enumeration constants as flags, i.e. as a series of powers of 2 starting with 1. The enumeration constants can be or-ed to form a bitvector (bitmask) which is encoded and decoded as a list of symbolic values in SOAP. For example:
enum * ns machineStatus{ ON, BELT, VALVE, HATCH};
int ns getMachineStatus(char *name, char *enum ns machineStatus result);
Note that the use of the enum does not require the asterisk, only the definition. The gSOAP compiler generates the enumeration:
enum ns machineStatus{ ON=1, BELT=2, VALVE=4, HATCH=8};
A remote method implementation in a Web service can return:
int ns getMachineStatus(struct soap *soap, char *name, enum ns machineStatus result) { ...
*result = BELT — HATCH; return SOAP OK;
}