sw_discovery

# sw_text_record

### OVERVIEW

The sw_text_record functions manage encoding data to a DNS style text record. Developers need not concern themselves with the underlying representation of this data.

### FUNCTION

## sw_text_record_init

### SYNOPSIS

    sw_result
    sw_text_record_init(
       sw_text_record * text_record)

### DESCRIPTION

Creates an empty text record.

`text_record`: The text record object

### EXAMPLE

    int func(void)
    {
       sw_text_record text_record;
       if (sw_text_record_init(&text_record) != SW_OKAY)
       {
          fprintf(stderr, "init failed\n");
          return -1;
       }
    }

### SEE ALSO

`sw_text_record_fina`

### FUNCTION

## sw_text_record_fina

### SYNOPSIS

    sw_result
    sw_text_record_fina(
       sw_text_record  text_record)

### DESCRIPTION

Deallocates all memory resources associated with this text record. Any attempt to use this text record after this call are undefined.

`text_record`: The text record object.

### EXAMPLE

    int func(void)
    {
       sw_text_record text_record;

       if (sw_text_record_init_(&text_record) != SW_OKAY)
       {
          fprintf(stderr, "init failed\n");
          return -1;
       }

       //
       // ... use text record
       //

       sw_text_record_fina(text_record);

### SEE ALSO

`sw_text_record_init`

### FUNCTION

## sw_text_record_add_string

### SYNOPSIS

    sw_result
    sw_discovery_add_string(
       sw_text_record  text_record,
       sw_const_string string)

### DESCRIPTION

Adds a new string to the text record. The string must be in the format specified by DNS text records (e.g. key|key=|key=val). The string must be no longer than 255 octets.

`text_record`: The text record object.

`string`: String to add to text record. UTF-8 encoded.

### EXAMPLE

    ...

    sw_text_record text_record;

    if (sw_text_record_init(&text_record) != SW_OKAY)
    {
      fprintf(stderr, "init failed\n");
      return -1;
    }

    if (sw_text_record_add_string(text_record, "Howl Rocks The House") != SW_OKAY)
    {
      fprintf(stderr, "add_string failed\n");
      return -1;
    }

    ...

    sw_text_record_fina(text_record);

### SEE ALSO

`sw_text_record_add_key_and_string_value`, `sw_text_record_add_key_and_binary_value`

### FUNCTION

## sw_text_record_add_key_and_string_value

### SYNOPSIS

    sw_result
    sw_text_record_add_key_and_string_value(
       sw_text_record                        text_record,
       sw_const_string                       key,
       sw_const_string                       val)

### DESCRIPTION

Adds a new key/value string to the text record. The parameter 'val' can be NULL. The combined string lengths of key and val must not exceed 254 octets.

`text_record`: The text record object.

`key`: A string denoting a lookup key for a value. UTF-8 encoded.

`val`: A string denoting the value for this duple. UTF-8 encoded.

### EXAMPLE

    ...

    sw_text_record text_record;

    if (sw_text_record_init(&text_record) != SW_OKAY)
    {
       fprintf(stderr, "init failed\n");
       return -1;
    }

    if (sw_text_record_add_key_and_string_value(text_record, "Machine ID", "9782385") != SW_OKAY)
    {
       fprintf(stderr, "add_key_and_string_value failed\n");
       return -1;
    }

    ...

    sw_text_record_fina(text_record);

### SEE ALSO

`sw_text_record_add_string`, `sw_text_record_add_key_and_binary_value`

### FUNCTION

## sw_text_record_add_key_and_binary_value

### SYNOPSIS

    sw_result
    sw_text_record_add_key_and_binary_value(
       sw_text_record                   text_record,
       sw_const_string                  key,
       sw_octets                        val,
       sw_ulong                         len)

### DESCRIPTION

Adds a new string key and binary value string to the text record. The parameter 'val' can be NULL, however in this case len must be 0. The combined string length of the key and val length must not exceed 254 octets. Please note that when marshaling binary data, the programmer is responsible for managing any and all byte ordering issues.

`text_record`: The text record object

`key`: A string denoting a lookup key for a value. UTF-8 encoded.

`val`: A string denoting the value for this duple.

`len`: The length of the val described in octets.

### EXAMPLE

    ...

    sw_text_record text_record;
    unsigned long  data;

    if (sw_text_record_init(&text_record) != SW_OKAY)
    {
       fprintf(stderr, "init failed\n");
       return -1;
    }

    data = 42;

    if (sw_text_record_add_key_and_binary_value(text_record, "Machine ID", (sw_octets) &data, sizeof(data)) != SW_OKAY)
    {
       fprintf(stderr, "add_key_and_string_value failed\n");
       return -1;
    }

    ...

    sw_text_record_fina(text_record);

### SEE ALSO

`sw_text_record_add_string`, `sw_text_record_add_key_and_string_value`

### FUNCTION

## sw_text_record_bytes

### SYNOPSIS

    sw_octets
    sw_text_record_bytes(
       sw_text_record                      text_record)

### DESCRIPTION

Returns a pointer to the byte buffer that holds the encoded text record. This byte buffer can be used as a parameter to sw_discovery_publish, or sw_discovery_publish_update.

`text_record`: The text record object.

### EXAMPLE

    ...

    sw_octets bytes = sw_text_record_bytes(text_record);

    ...

### SEE ALSO

`sw_text_record_len`

### FUNCTION

## sw_text_record_len

### SYNOPSIS

    sw_ulong
    sw_text_record_len(
       sw_text_record                 text_record)

### DESCRIPTION

Returns the length of the encoded text record buffer. This value can be used as a parameter to sw_discovery_publish, and sw_discovery_publish_update.

`text_record`: The text record object.

### EXAMPLE

    ...

    sw_ulong = sw_text_record_len(text_record);

SEE ALSO:

`sw_text_record_bytes`