[PluginSDK] API Features & Issues Collection

[Philosound]

Disclaimer: This thread is not for end-users, but for plugin and sdk developers. If you're here to request a plugin, feature or plugin crash fix, this is the wrong place. Use the plugin's official support thread or create a thread if not applicable.

This collection is supposed to be both for the devs to quickly gain an oversight on what's going on at the plugin API front, as well as for plugin developers to have a centralized point to benefit from each others experiences.


API Additions & Change Requests
Oh, if only I could...

• assign hotkeys from inside the plugin dynamically [remarks]
• toggle 3dsoundenabled (assumption: write to database not having immediate effect)

• have a seperate state variable for "do 3d processing on this client" instead of it depending on the position of that client relative to the listener

  [reference]
• echo reduction (as opposed to cancellation) isn't available in the API

API Bugs
It's a bug, not a feature!

• onEditPostProcessVoiceDataEvent, onEditPlaybackVoiceDataEvent: id corruption on whisper [workaround] Status: In Tracker
• Sending whispers isn't caught by tree view, shown as talk in taskbar on sender, shown correctly on recipient [reference]
• setWhisperList not calling onServerErrorEvent with returnCode [reference] possibly related to above
• Audio callbacks are bypassed for recording [reference]

API Quirks
Not really a bug, but unexpected, easily overlooked? This list is about those things.

• Note that users can enable & disable your plugin while connected. The client won't bring you up to speed in that case. [example]
• Bug-ish: onPluginCommandEvent, hotkeys use the plugin file name, minus _someOs, not ts3plugin_name(). Watch for case-sensitivy (e.g. toLower) and such
• If you're crashing the client without it being able to create a dump file, watch for thread related issues like console debug.

Plugin Ecosystem
Package Installer not working on C64? Auto-Updater anniversary? This list is about those things.

• OpenSSL could be optionally supported if found on system instead of flat-out disabled [reference] - included in 3.0.14
• Download page requires API Version filtering

[Philosound]

Example reply.
Cross-referencing that report, this should be added to the bug list!

[Philosound]

_requestClientSetWhisperList:

Returns ERROR_ok on success

I don't know about the client sdk, but with the plugin sdk it does not.

[Screech]

Plugin Ecosystem
Package Installer not working on C64? Auto-Updater anniversary? This list is about those things.

• Download page requires API Version filtering

Very much agree, been asking for that since the plugin contest during the beta. Supported OS filter would not be a bad idea to add too, but the API version is a higher priority to me.

[Philosound]

Given the rare nature of API ups, I'm gonna do sth. that might look like a reminding bump of this collection, while it is ofc only the commit message that I moved the SSL request out of the API additions category since it doesn't require changes to the API itself

[ScP]

Improvements:

There's this thingy about the list of parameters for ts3plugin_onTextMessageEvent(). The third parameter (toID) is pretty much useless in its current implementation. Here's why:

1. When the message is sent to the server, the toID is always 0. This is perfectly normal and you don't really need the parameter for this type of text message.
2. When the message is sent to the channel, the toID is also 0. I would expect this parameter to indicate the ID of the channel where you've received the message, but since the toID is an anyID it cannot be used for channel IDs as those can get very large and therefore are uint64 numbers.
3. When the message is sent private, your own client is the target and there's also no need for the information stored in that parameter as you know your own ID.

I'd like to see the type of toID changed to uint64 and have it contain the channel ID on channel chat messages.

---

Feature Requests:

I'd like to have the ability to change the active server/chat tab.

// switch active server tab by server connection handler ID
unsigned int (*switchServerConnectionHandler)(uint64 serverConnectionHandlerID);

// get active chat tab by server connection handler ID
unsigned int (*getCurrentTab)(uint64 serverConnectionHandlerID, anyID* type, anyID* toID);

// set active chat tab by server connection handler ID
unsigned int (*setCurrentTab)(uint64 serverConnectionHandlerID, anyID type, anyID toID);

For getCurrentTab() and setCurrentTab(), the mode could simply use the existing TextMessageTargetMode values while toID could be the client ID for private chat tabs (or 0 for other tabs as you can only have one server/channel tab open per connection).

I'd also like to find out if a client is on my list of friends or blocked people.

// get client contact type by unique identifier
unsigned int (*getClientContactType)(const char* clientUID, anyID result);

---

Bugs:

The ts3plugin_onFileTransferStatusEvent() is not fired when a file transfer starts.

[NouberNou]

I think this might be a bug, or I might be drunk...

So in the voice buffer call backs the channelSpeakerArray is giving me odd values. I have a stereo mic and the channels argument is being passed in as 2, but the values in channelSpeakerArray are off for SPEAKER_FRONT_LEFT and SPEAKER_FRONT_RIGHT from what you have in your defines.

When I spit them out using a printf format of %08x I get for SPEAKER_FRONT_LEFT 0x10000000 and for SPEAKER_FRONT_RIGHT I get 0x20000000. Your defines have them set as 0x1 and 0x2, which when expanded out at compile time equal 0x00000001 and 0x00000002 using printf %08x.

Any idea on what is going on here?

[NouberNou]

Figured it out, Windows Audio Session does not return the same bit mask values as DirectSound (makes sense, since you are using DS define values)...

You aren't planning on removing Direct Sound any time in the near future are you?

[twprogrammers]

It seems that this is the thread for API requests, so I placed it here. If I am wrong, I apologize and be grateful if it could be moved to the right place.

I was looking through the plugin docs for a way to modify the client's description, and I came up dry. So if there is and I failed to find it, I apologize for the mistake.

I would like to request a new section of the API for modifying all clients properties, such as the avatar, the description, name, groups, etc.

[Foxtrott]

There is no documentation to be found on PluginCommands.
I couldn't find documentation for:
sendPluginCommand
ts3plugin_onPluginCommandEvent
in the plugin sdk documentation.
The one available in the Downloads section is "Revision 2016-01-19 16:13:04"
For good practice I also checked the Client and Server SDK docs "Revision 2015-04-10 16:42:26" and "Revision 2015-03-30 09:54:33" respectively.
I'm sure there are more docs missing but i don't have time to check them all.
I wanted to know if the command has to be a valid text char* or if i can also use a binary format. Of cause i cant use 0x0's in the command. But does the UTF-8 bad chars filter apply to the commands?

[Thomas]

Missing events:
onMessageListFinishedEvent
onBanListFinishedEvent
onComplainListFinishedEvent
onServerGroupByClientIDFinishedEvent
onServerGroupClientListFinishedEvent

For example, there is a onMessageListEvent, but unlike other "listevents", there is no finishing event. Same for the others in the list above.


Missing functions:
requestServerLog
requestClientServerQueryLogin
requestServerConnectionInfo

There are events that trigger, if the client requests that kind of info, but no way to request that type of information as a plugin.


(Highly) undocumented:
channelPropertyStringToFlag (I tried strings like "CHANNEL_NAME" or "CHANNEL_TOPIC", to hopefully receive the right enum value, but had no luck [they yield a converterror 1540]; I don't know valid input values or what the output would be)
clientPropertyStringToFlag (same as above)
serverPropertyStringToFlag (same as above)
cleanUpConnectionInfo (no clue, what this is)


Maybe someone has some information on any of these functions/events.

[Chris]

channelPropertyStringToFlag (I tried strings like "CHANNEL_NAME" or "CHANNEL_TOPIC", to hopefully receive the right enum value, but had no luck [they yield a converterror 1540]; I don't know valid input values or what the output would be)
clientPropertyStringToFlag (same as above)
serverPropertyStringToFlag (same as above)

They translate the properties as used for example in server query commands to the constants that have to be used in the pluginSDK functions.

	auto prop = "virtualserver_name";
	size_t flag = std::numeric_limits<size_t>::max();
	auto err = ts3.serverPropertyStringToFlag(prop, &flag);
	// flag == 1 (defined as VIRTUALSERVER_NAME)
	// err == 0 (defined as ERROR_ok)

[Thomas]

Thx, I didn't try lowercase values.

[Master_D]

While implementing a plugin, i have found something i do not understand.

When i try to read my own idletime, the function always return "0".
When reading the header-file in the plugin-sdk, there is mentioned "internal use" as a comment within the enum.

Is this intended and/or is it possible to change this behaviour?

[Albord]

In plugin sdk
_requestServerTemporaryPasswordAdd
At least in duplicate entry error, returns ERROR_OK
(NOT A BUG, concept mistake, the error is called in the function onServerErrorEvent)