1.5. Attributes Objects

1.5.1. Creating An Attributes Object

In the following example, the call to lbm_context_attr_create() creates the custom attributes object, and initializes each attribute from the current default values. Subsequent calls to lbm_context_attr_setopt() or lbm_context_attr_str_setopt() modify only the attributes object values.

lbm_context_attr_t * attrib;
int rc;
int errnum;
const char * errmsg;

rc = lbm_context_attr_create(&attrib);
if (rc != 0)
{
   errnum = lbm_errnum();
   errmsg = lbm_errmsg();
   fprintf(stderr, "Error %d returned from lbm_context_attr_create(), %s\n",
      errnum, errmsg);
}

This example also illustrates the proper way to determine the success or failure of an UM API call. Most UM API calls return 0 to indicate success, and -1 to indicate failure. To retrieve the specific UM error code for the failure, call lbm_errnum(). To retrieve a text string describing the error code, call lbm_errmsg().

1.5.2. Setting an Option from a Binary Value

For an option of type other than "string", call lbm_context_attr_setopt() to set its value. (See the C API reference for details on this function.) The final two parameters in the function are a pointer to a variable containing the option value, and a pointer to a variable of type size_t that contains the correct length of the option value variable.

UM options are of three general types that:

• accept values in a well-defined range (Examples include context transport_tcp_port_low and context transport_tcp_port_high. Each requires a value which corresponds to a valid TCP port number.)

• accept values from an enumerated set, (For example, context operational_mode. Manifest constants are provided in lbm.h for each permitted value. In the case of context operational_mode, those constants are LBM_CTX_ATTR_OP_EMBEDDED and LBM_CTX_ATTR_OP_SEQUENTIAL.)

• act as switches, enabling or disabling a particular feature (For example, context resolver_cache. The set of allowed values is limited to 0 (indicating off, no, false, or disabled), and 1, indicating on, yes, true, or enabled.)

The example code below sets four options. First, we set the operational mode to sequential. Then we set the transport TCP port low and high values to 4901 and 4920, respectively. Finally, we tell UM that our application will not be using multiple sending threads per transport session.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;
unsigned short int optval;
size_t optlen;

/* Set the operational_mode */
optlen = sizeof(optval);
optval = LBM_CTX_ATTR_OP_SEQUENTIAL;
rc = lbm_context_attr_setopt(attrib, "operational_mode", &optval, optlen);
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_tcp_port_low */
optlen = sizeof(optval);
optval = 4901;
rc = lbm_context_attr_setopt(attrib, "transport_tcp_port_low", &optval, optlen);
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_tcp_port_high */
optlen = sizeof(optval);
optval = 4920;
rc = lbm_context_attr_setopt(attrib, "transport_tcp_port_high", &optval, optlen);
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_session_multiple_sending_threads */
optlen = sizeof(optval);
optval = 0;
rc = lbm_context_attr_setopt(attrib, "transport_session_multiple_sending_threads",
                             &optval, optlen);
if (rc != 0)
{
   /* Handle error */
}

1.5.3. Setting an Option from a String Value

Setting an option from a string value effectively does the same thing that setting an option from a binary value does. However, the option value is passed as a null-terminated string, rather than as value and length pointers. UM uses this mechanism to process options in a configuration file. Thus, the format used for option values must match the format you would use in a configuration file.

In the following example, as before, we set the operational mode to sequential. Then we set the transport TCP port low and high values to 4901 and 4920, respectively. Finally, we tell UM that our application will not be using multiple sending threads per transport session.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;

/* Set the operational_mode */
rc = lbm_context_attr_str_setopt(attrib, "operational_mode", "sequential");
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_tcp_port_low */
rc = lbm_context_attr_str_setopt(attrib, "transport_tcp_port_low", "4901");
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_tcp_port_high */
rc = lbm_context_attr_str_setopt(attrib, "transport_tcp_port_high", "4920");
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_session_multiple_sending_threads */
rc = lbm_context_attr_str_setopt(attrib, "transport_session_multiple_sending_threads",
                                 "0");
if (rc != 0)
{
   /* Handle error */
}

1.5.4. Getting an Option as a Binary Value

Getting an option as a binary value is very similar to setting an option from a binary value: it requires knowledge of not only the option name, but its type as well. The final two parameters in the call to lbm_context_attr_getopt() are a pointer to a variable to receive the current option value, and a pointer to a variable of type size_t which contains the length of the option value variable. This length must be be correct for the specified option.

In the example code below, we set the option values for operational mode, the transport TCP port low and high values, and retrieve multiple sending threads.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;
unsigned short int optval;
size_t optlen;

/* Get the operational_mode */
optlen = sizeof(optval);
rc = lbm_context_attr_getopt(attrib, "operational_mode", &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains LBM_CTX_ATTR_OP_EMBEDDED or LBM_CTX_ATTR_OP_SEQUENTIAL */

/* Get transport_tcp_port_low */
optlen = sizeof(optval);
rc = lbm_context_attr_getopt(attrib, "transport_tcp_port_low", &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains the value of transport_tcp_port_low, which should be 4901 */

/* Get transport_tcp_port_high */
optlen = sizeof(optval);
rc = lbm_context_attr_getopt(attrib, "transport_tcp_port_high", &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains the value of transport_tcp_port_high, which should be 4920 */

/* Get transport_session_multiple_sending_threads */
optlen = sizeof(optval);
rc = lbm_context_attr_getopt(attrib, "transport_session_multiple_sending_threads",
                             &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains the value of transport_session_multiple_sending_threads,
   which should be 0. */

1.5.5. Getting an Option as a String Value

Getting an option as a string value effectively does the same thing that getting an option as a binary value does. However, the option value is returned as a null-terminated string, just as you would specify the option value in a configuration file. The final two parameters in the call to lbm_context_attr_str_getopt() are a pointer to a string variable to receive the current option value, and a pointer to a variable of type size_t which contains the maximum size of the option value string variable.

In the example code below, the option values for operational mode, the transport TCP port low and high values, and multiple sending threads are retrieved.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;
char optval_string[256];

/* Get the operational_mode */
optlen = sizeof(optval_string);
rc = lbm_context_attr_str_getopt(attrib, "operational_mode", optval_string, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval_string now contains either "embedded" or "sequential" */

/* Get transport_tcp_port_low */
optlen = sizeof(optval_string);
rc = lbm_context_attr_str_getopt(attrib, "transport_tcp_port_low",
                                 optval_string, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval_string now contains the string value of transport_tcp_port_low,
   which should be "4901" */

/* Get transport_tcp_port_high */
optlen = sizeof(optval_string);
rc = lbm_context_attr_str_getopt(attrib, "transport_tcp_port_high",
                                 optval_string, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval_string now contains the string value of transport_tcp_port_high,
   which should be "4920" */

/* Get transport_session_multiple_sending_threads */
optlen = sizeof(optval_string);
rc = lbm_context_attr_str_getopt(attrib, "transport_session_multiple_sending_threads",
                                 optval_string, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval_string now contains the value of transport_session_multiple_sending_threads,
   which should be "0". */

1.5.6. Deleting an Attributes Object

Once the attributes object is no longer needed, it should be deleted.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;

rc = lbm_context_attr_delete(attrib);
if (rc != 0)
{
   /* Handle error */
}

1.5.7. Restrictions

There are no restrictions on setting options via attributes objects. Any option which can be set via a configuration file, can also be set via an attributes object. In addition, attributes objects allow setting certain options (such as function pointers) which cannot be set with a configuration file.