QoS sendmsg() API extensions

The sendmsg() function is used to send data, ancillary data, or a combination of these through a connected or unconnected socket.

The sendmsg() API allows for quality of service (QoS) classification data. QoS policies use this function to define a more granular classification level for outgoing or incoming TCP/IP traffic. They specifically use ancillary data types that apply to the IP layer. The message type used is IP_QOS_CLASSIFICATION_DATA. This ancillary data can be used by the application to define attributes for traffic in a particular TCP connection. If the attributes passed by the application match the attributes defined in the QoS policy, then the TCP traffic is restricted by the policy.

Use the following information to initialize the IP_QOS_CLASSIFICATION_DATA structure:

• ip_qos_version: Indicates version of the structure. This must be filled in using the constant IP_QOS_CURRENT_VERSION.

• ip_qos_classification_scope: Specify a connection level scope (use constant IP_QOS_CONNECTION_LEVEL) or a message level scope (constant IP_QOS_MESSAGE_LEVEL).

  Connection level scope indicates that the QoS service-level obtained through classification of this message will remain in effect for all subsequent messages sent until the next sendmsg() with QoS classification data. Message level scope indicates that the QoS service level assigned will only be used for the message data included in this sendmsg() call. Future data sent without QoS classification data will inherit the previous connection level QoS assignment (from last Connection Level classification through sendmsg() or from the original TCP connection classification during connection establishment).

• ip_qos_classification_type: This specification indicates the type of classification data being passed. An application can chose to pass an application defined token, an application specified priority, or both a token and a priority. If the latter option is selected the two selected, classification types must be logically 'OR'ed. The following types can be specified:
  • Application defined token classification. A single type must be specified; if more than one is specified, the results are unpredictable.
    • IP_SET_QOSLEVEL_W_APPL_TOKEN_ASCII: This indicates that the classification data is a character string in ASCII format. When this option is specified, the application token needs to be passed in the ip_qos_appl_token field.
      Note: If the application needs to pass numeric values for the classification data it must first convert them to printable ASCII format. Also note that the string specified can be in mixed case and will be used in the exact format specified for comparison purposes.
    • IP_SET_QOSLEVEL_W_APPL_TOKEN_EBCDIC: Same as above except that the string is in EBCDIC format.
      Note: The IP_SET_QOSLEVEL_W_APPL_TOKEN_ASCII does perform slightly better than this option as the application data specified in the policy is saved in ASCII format inside of the TCP/IP stack, thereby eliminating the need to translate the application defined token on every sendmsg() request.
  • Application defined priority classification. A single type must be specified; if multiple priority types are specified, the results are unpredictable.
    • IP_SET_QOSLEVEL_EXPIDITED: Indicates that Expedited priority is requested
    • IP_SET_QOSLEVEL_HIGH: Indicates that High priority is requested
    • IP_SET_QOSLEVEL_MEDIUM: Indicates that Medium priority is requested
    • IP_SET_QOSLEVEL_LOW: Indicates that Low priority is requested
    • IP_SET_QOSLEVEL_BEST_EFFORT: Indicates that Best Effort priority is requested
  • ip_qos_appl_token_len: length of the ip_qos_appl_token specified.
  • ip_qos_appl_token: This "virtual field" immediately follows the ip_qos_classification_type field. The application classification token string in either ASCII or EBCDIC format depending on which flavor of IP_SET_QOSLEVEL_W_APPL_TOKEN_xxxx was specified for the classification type. This field is only referenced when an application defined token type is specified. Note that this string must not exceed 128 bytes. If a larger size is specified, only the first 128 bytes will be used. Also note that the length of the string is determined based on the value specified for cmsg_len (cmsg_len - sizeof(cmsghdr) - sizeof(ip_qos_classification_data)). This calculated length must not include any null terminating characters.