Channel information
| Retrieve and store information |

### Channel information

Querying and modifying information related to channels is similar to dealing with clients. The functions to query channel information are:

`unsigned int ts3client_getChannelVariableAsInt(` | serverConnectionHandlerID, |
| channelID, |
| flag, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`anyID channelID`;
`ChannelProperties flag`;
`int* result`;

`unsigned int ts3client_getChannelVariableAsString(` | serverConnectionHandlerID, |
| channelID, |
| flag, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`anyID channelID`;
`ChannelProperties flag`;
`char* result`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the information for the specified channel is requested.

- `channelID`

  ID of the channel whose property is queried.

- `flag`

  Channel propery to query, see below.

- `result`

  Address of a variable which receives the result value as int or string, depending on which function is used. In case of a string, memory must be released using `ts3client_freeMemory`, unless an error occured.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`. For the string version: If an error has occured, the result string is uninitialized and must not be released.

The parameter `flag` specifies the type of queried information. It is defined by the enum ChannelProperties:

    enum ChannelProperties {
      CHANNEL_NAME = 0,             //Available for all channels that are "in view", always up-to-date
      CHANNEL_TOPIC,                //Available for all channels that are "in view", always up-to-date
      CHANNEL_DESCRIPTION,          //Must be requested (=> requestChannelDescription)
      CHANNEL_PASSWORD,             //not available client side
      CHANNEL_CODEC,                //Available for all channels that are "in view", always up-to-date
      CHANNEL_CODEC_QUALITY,        //Available for all channels that are "in view", always up-to-date
      CHANNEL_MAXCLIENTS,           //Available for all channels that are "in view", always up-to-date
      CHANNEL_MAXFAMILYCLIENTS,     //Available for all channels that are "in view", always up-to-date
      CHANNEL_ORDER,                //Available for all channels that are "in view", always up-to-date
      CHANNEL_FLAG_PERMANENT,       //Available for all channels that are "in view", always up-to-date
      CHANNEL_FLAG_SEMI_PERMANENT,  //Available for all channels that are "in view", always up-to-date
      CHANNEL_FLAG_DEFAULT,         //Available for all channels that are "in view", always up-to-date
      CHANNEL_FLAG_PASSWORD,        //Available for all channels that are "in view", always up-to-date
      CHANNEL_ENDMARKER,
    };

- `CHANNEL_NAME`

  String: Name of the channel.

- `CHANNEL_TOPIC`

  String: Single-line channel topic.

- `CHANNEL_DESCRIPTION`

  String: Optional channel description. Can have multiple lines. Clients need to request updating this variable for a specified channel using:

  `unsigned int ts3client_requestChannelDescription(` | serverConnectionHandlerID, |
  | channelID, |
  | returnCode`)`; |

  `anyID serverConnectionHandlerID`;
  `anyID channelID`;
  `const char* returnCode`;

- `CHANNEL_PASSWORD`

  String: Optional password for password-protected channels.

  | Note
  Clients can only set this value, but not query it.

  If a password is set or removed by modifying this field, `CHANNEL_FLAG_PASSWORD` will be automatically adjusted.

- `CHANNEL_CODEC`

  Int (0-3): Codec used for this channel:

  - 0 - Speex Narrowband (8 kHz)

  - 1 - Speex Wideband (16 kHz)

  - 2 - Speex Ultra-Wideband (32 kHz)

  See Sound codecs.

- `CHANNEL_CODEC_QUALITY`

  Int (0-10): Quality of channel codec of this channel. Valid values range from 0 to 10, default is 7. Higher values result in better speech quality but more bandwidth usage.

  See Encoder options.

- `CHANNEL_MAXCLIENTS`

  Int: Number of maximum clients who can join this channel.

- `CHANNEL_MAXFAMILYCLIENTS`

  Int: Number of maximum clients who can join this channel and all subchannels.

- `CHANNEL_ORDER`

  Int: Defines how channels are sorted in the GUI. Channel order is the ID of the predecessor channel after which this channel is to be sorted. If 0, the channel is sorted at the top of its hirarchy.

  For more information please see the chapter Channel sorting.

- `CHANNEL_FLAG_PERMANENT` / `CHANNEL_FLAG_SEMI_PERMANENT`

  Concerning channel durability, there are three types of channels:

  - Temporary

    Temporary channels have neither the `CHANNEL_FLAG_PERMANENT` nor `CHANNEL_FLAG_SEMI_PERMANENT` flag set. Temporary channels are automatically deleted by the server after the last user has left and the channel is empty. They will not be restored when the server restarts.

  - Semi-permanent

    Semi-permanent channels are not automatically deleted when the last user left but will not be restored when the server restarts.

  - Permanent

    Permanent channels will be restored when the server restarts.

- `CHANNEL_FLAG_DEFAULT`

  Int (0/1): Channel is the default channel. There can only be one default channel per server. New users who did not configure a channel to join on login in `ts3client_startConnection` will automatically join the default channel.

- `CHANNEL_FLAG_PASSWORD`

  Int (0/1): If set, channel is password protected. The password itself is stored in `CHANNEL_PASSWORD`.

To modify channel data use

`unsigned int ts3client_setChannelVariableAsInt(` | serverConnectionHandlerID, |
| channelID, |
| flag, |
| value`)`; |

`anyID serverConnectionHandlerID`;
`anyID channelID`;
`ChannelProperties flag`;
`int value`;

`unsigned int ts3client_setChannelVariableAsString(` | serverConnectionHandlerID, |
| channelID, |
| flag, |
| value`)`; |

`anyID serverConnectionHandlerID`;
`anyID channelID`;
`ChannelProperties flag`;
`const char* value`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the information for the specified channel should be changed.

- `channelID`

  ID of the channel whoses property should be changed.

- `flag`

  Channel propery to change, see above.

- `value`

  Value the channel property should be changed to.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`.

| Important
After modifying one or more channel variables, you have to flush the changes to the server.
`unsigned int ts3client_flushChannelUpdates(` | serverConnectionHandlerID, |
| channelID`)`; |
`anyID serverConnectionHandlerID`; `anyID channelID`; Parameters `serverConnectionHandlerID` ID of the server connection handler to which the channel changes should be flushed. `channelParentID` ID of the channel of which the changed properties should be flushed. Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`.

As example, to change the channel name and topic:

    /* Modify data 1 */
    if(ts3client_setChannelVariableAsString(scHandlerID, channelID, CHANNEL_NAME,
                                            "Other channel name") != ERROR_ok) {
        printf("Error setting channel name\n");
        return;
    }

    /* Modify data 2 */
    if(ts3client_setChannelVariableAsString(scHandlerID, channelID, CHANNEL_TOPIC,
                                            "Other channel topic") != ERROR_ok) {
    printf("Error setting channel topic\n");
        return;
    }

    /* Flush changes */
    if(ts3client_flushChannelUpdates(scHandlerID, channelID) != ERROR_ok) {
        printf("Error flushing channel updates\n");
        return;
    }

After a channel was edited using `ts3client_setChannelVariableAsInt` or `ts3client_setChannelVariableAsString` and the changes were flushed to the server, the edit is announced with the event:

`void onUpdateChannelEditedEvent(` | serverConnectionHandlerID, |
| channelID, |
| invokerID, |
| invokerName, |
| invokerUniqueIdentifier`)`; |

`anyID serverConnectionHandlerID`;
`anyID channelID`;
`anyID invokerID`;
`const char* invokerName`;
`const char* invokerUniqueIdentifier`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the channel has been edited.

- `channelID`

  ID of edited channel.

- `invokerID`

  ID of the client who edited the channel.

- `invokerName`

  String with the name of the client who edited the channel.

- `invokerUniqueIdentifier`

  String with the unique ID of the client who edited the channel.

To find the channel ID from a channels path:

`unsigned int ts3client_getChannelIDFromChannelNames(` | serverConnectionHandlerID, |
| channelNameArray, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`char** channelNameArray`;
`anyID* result`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the channel ID is queried.

- `channelNameArray`

  Array defining the position of the channel: "grandparent", "parent", "channel", "". The array is terminated by an empty string.

- `result`

  Address of a variable which receives the queried channel ID.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`.

Retrieve and store information |  | Channel sorting