release version 2.4

- introduces the access control and chat functionality
- Python bindings are included in the offical supported package

Author: Korbinian Kram

Bindings/Python/CMakeLists.txt

@@ -33,6 +33,8 @@ set(SOURCE
 	PyAccessControlModule.h
 	PyAgentConnection.cpp
 	PyAgentConnection.h
+	PyChatModule.cpp
+	PyChatModule.h
 	PyInstantSupportModule.cpp
 	PyInstantSupportModule.h
 	PyLogging.cpp

Bindings/Python/PyAccessControlModule.cpp

@@ -40,22 +40,34 @@ namespace
 
 // Methods
 
-PyObject* PyAccessControlModule_setCallbacks(PyAccessControlModule* self, PyObject* arg)
+PyObject* PyAccessControlModule_setCallbacks(
+	PyAccessControlModule* self,
+	PyObject* args,
+	PyObject* kwargs)
 {
 	using Feature = tvagentapi::IAccessControlModule::Feature;
 	using Access = tvagentapi::IAccessControlModule::Access;
 
-	if (!PyDict_Check(arg))
+	char accessChangedArgName[] = "accessChangedCallback";
+	char accessRequestArgName[] = "accessRequestCallback";
+
+	PyObject* accessChangedCallback = Py_None;
+	PyObject* accessRequestCallback = Py_None;
+
+	char* kwargList[] = {accessChangedArgName, accessRequestArgName, {}};
+	if (!PyArg_ParseTupleAndKeywords(
+		args,
+		kwargs,
+		"|OO:setCallbacks",
+		kwargList,
+		&accessChangedCallback,
+		&accessRequestCallback))
 	{
-		PyErr_Format(PyExc_TypeError, "expected dict instance, got %R", arg);
 		return nullptr;
 	}
 
-	const char* accessChangedCbkName = "accessChangedCallback";
-	const char* accessRequestCbName = "accessRequestCallback";
-
-	PyObject* accessChangedCallback = PyDict_GetItemString(arg, accessChangedCbkName);
-	PyObject* accessRequestCallback = PyDict_GetItemString(arg, accessRequestCbName);
+	accessChangedCallback = accessChangedCallback == Py_None ? nullptr : accessChangedCallback;
+	accessRequestCallback = accessRequestCallback == Py_None ? nullptr : accessRequestCallback;
 
 	if (accessChangedCallback && !PyCallable_Check(accessChangedCallback))
 	{
@@ -214,48 +226,114 @@ PyObject* PyAccessControlModule_rejectAccessRequest(PyAccessControlModule* self,
 	return NoneOrInternalError(self->m_module->rejectAccessRequest(feature));
 }
 
+namespace DocStrings
+{
+
+PyDoc_STRVAR(isSupported,
+R"__(isSupported($self)
+--
+
+Returns whether the current module is supported by the SDK and the IoT Agent counterpart.
+
+:return True if the current module is supported, False otherwise.
+)__");
+
+PyDoc_STRVAR(setCallbacks,
+R"__(setCallbacks($self,
+	accessChangedCallback=None,
+	accessRequestCallback=None)
+--
+
+Sets callbacks to handle Access changes and incoming access confirmation requests.
+
+:param accessChangedCallback: called when an Access permission for a specific Feature has been changed
+:type accessChangedCallback: callback(tvagentapi.IAccessControlModule.Feature feature, tvagentapi.IAccessControlModule.Access access)
+:param accessRequestCallback: called when a remote party attempts to use a feature whose current Access permission is set to "After Confirmation"
+:type accessRequestCallback: callback(tvagentapi.IAccessControlModule.Feature feature)
+)__");
+
+PyDoc_STRVAR(getAccess,
+R"__(getAccess($self, feature)
+--
+
+Requests the current Access permission for the given Feature.
+
+:param tvagentapi.IAccessControlModule.Feature feature: Feature for which the current access permission is being queried.
+:return Access permission enum value.
+)__");
+
+PyDoc_STRVAR(setAccess,
+R"__(setAccess($self, feature, access)
+--
+
+Sets the given Access permission for the given Feature.
+
+:param tvagentapi.IAccessControlModule.Feature feature: Feature for which the current access permission is being set.
+:param tvagentapi.IAccessControlModule.Access access: Access permission being set for the feature.
+)__");
+
+PyDoc_STRVAR(acceptAccessRequest,
+R"__(acceptAccessRequest($self, feature)
+--
+
+Accepts an incoming access request for the given feature.
+
+:param tvagentapi.IAccessControlModule.Feature feature: Feature for which request is accepted.
+)__");
+
+PyDoc_STRVAR(rejectAccessRequest,
+R"__(rejectAccessRequest($self, feature)
+--
+
+Rejects an incoming access request for the given feature.
+
+:param tvagentapi.IAccessControlModule.Feature feature: Feature for which request is rejected.
+)__");
+
+} // namespace DocStrings
+
 PyMethodDef PyAccessControlModule_methods[] =
 {
+	{
+		"isSupported",
+		WeakConnectionCall<PyAccessControlModule, PyAccessControlModule_isSupported>,
+		METH_NOARGS,
+		DocStrings::isSupported
+	},
+
 	{
 		"setCallbacks",
-		WeakConnectionCall<PyAccessControlModule, PyAccessControlModule_setCallbacks>,
-		METH_O,
-		"set access control callbacks"
+		PyCFunctionCast(WeakConnectionCall<PyAccessControlModule, PyAccessControlModule_setCallbacks>),
+		METH_VARARGS | METH_KEYWORDS,
+		DocStrings::setCallbacks
 	},
 
 	{
 		"getAccess",
 		WeakConnectionCall<PyAccessControlModule, PyAccessControlModule_getAccess>,
 		METH_O,
-		"for given Feature fetch Access mode"
+		DocStrings::getAccess
 	},
 
 	{
 		"setAccess",
 		WeakConnectionCall<PyAccessControlModule, PyAccessControlModule_setAccess>,
 		METH_VARARGS,
-		"for given Feature set Access mode"
-	},
-
-	{
-		"isSupported",
-		WeakConnectionCall<PyAccessControlModule, PyAccessControlModule_isSupported>,
-		METH_NOARGS,
-		"check if the module is supported"
+		DocStrings::setAccess
 	},
 
 	{
 		"acceptAccessRequest",
 		WeakConnectionCall<PyAccessControlModule, PyAccessControlModule_acceptAccessRequest>,
 		METH_O,
-		"for given Feature accept incoming access request"
+		DocStrings::acceptAccessRequest
 	},
 
 	{
 		"rejectAccessRequest",
 		WeakConnectionCall<PyAccessControlModule, PyAccessControlModule_rejectAccessRequest>,
 		METH_O,
-		"for given Feature reject incoming access request"
+		DocStrings::rejectAccessRequest
 	},
 
 	{} // Sentinel

Bindings/Python/PyAgentConnection.cpp

@@ -30,6 +30,7 @@
 #include "PyAccessControlModule.h"
 #include "PyInstantSupportModule.h"
 #include "PyTVSessionManagementModule.h"
+#include "PyChatModule.h"
 #include "PyLogging.h"
 #include "PyTVAgentAPI.h"
 #include "PythonHelpers.h"
@@ -123,6 +124,9 @@ PyObject* PyAgentConnection_getModule(PyAgentConnection* self, PyObject* arg)
 				case tvagentapi::IModule::Type::TVSessionManagement:
 					return reinterpret_cast<PyObject*>(
 						MakeWrapperObject<PyTVSessionManagementModule>(self));
+				case tvagentapi::IModule::Type::Chat:
+					return reinterpret_cast<PyObject*>(
+						MakeWrapperObject<PyChatModule>(self));
 			}
 			PyErr_BadInternalCall();
 			return nullptr;
@@ -133,26 +137,36 @@ PyObject* PyAgentConnection_getModule(PyAgentConnection* self, PyObject* arg)
 	return pyModule;
 }
 
-PyObject* PyAgentConnection_setStatusChangedCallback(PyAgentConnection* self, PyObject* args)
+PyObject* PyAgentConnection_setCallbacks(
+	PyAgentConnection* self,
+	PyObject* args,
+	PyObject* kwargs)
 {
-	PyObject* arg = Py_None;
-	// parse optional argument (if not present, 'arg' won't be initialized)
-	if (!PyArg_ParseTuple(args, "|O", &arg))
+	PyObject* statusChangedArg = Py_None;
+
+	char statusChangedArgName[] = "statusChanged";
+	char* kwargList[] = {statusChangedArgName, {}};
+	if (!PyArg_ParseTupleAndKeywords(
+		args,
+		kwargs,
+		"|O:setCallbacks",
+		kwargList,
+		&statusChangedArg))
 	{
 		return nullptr;
 	}
 
-	PyObject* callable = arg == Py_None ? nullptr : arg;
+	statusChangedArg = statusChangedArg == Py_None ? nullptr : statusChangedArg;
 
-	if (callable && !PyCallable_Check(callable))
+	if (statusChangedArg && !PyCallable_Check(statusChangedArg))
 	{
-		PyErr_Format(PyExc_TypeError, "%R is not callable", callable);
+		PyErr_Format(PyExc_TypeError, "%R is not callable", statusChangedArg);
 		return nullptr;
 	}
 
-	Py_XINCREF(callable);
+	Py_XINCREF(statusChangedArg);
 	Py_XDECREF(self->m_pyStatusChangedCallback);
-	self->m_pyStatusChangedCallback = callable;
+	self->m_pyStatusChangedCallback = statusChangedArg;
 
 	auto statusChangedCallback = [](
 		tvagentapi::IAgentConnection::Status status,
@@ -172,9 +186,9 @@ PyObject* PyAgentConnection_setStatusChangedCallback(PyAgentConnection* self, Py
 		Py_DECREF(enumVal);
 	};
 
-	if (callable)
+	if (statusChangedArg)
 	{
-		self->m_connection->setStatusChangedCallback({statusChangedCallback, callable});
+		self->m_connection->setStatusChangedCallback({statusChangedCallback, statusChangedArg});
 	}
 	else
 	{
@@ -184,37 +198,93 @@ PyObject* PyAgentConnection_setStatusChangedCallback(PyAgentConnection* self, Py
 	Py_RETURN_NONE;
 }
 
+namespace DocStrings
+{
+
+PyDoc_STRVAR(start,
+R"__(start($self)
+--
+
+Tries to establish a connection to a running TeamViewer IoT Agent and maintains it until stop() is called.
+The connection is re-established automatically if it was lost.
+To be notified about the connectivity, set the statusChanged callback.
+)__");
+
+PyDoc_STRVAR(stop,
+R"__(stop($self)
+--
+
+Shuts down all communication with the TeamViewer IoT Agent and changes state afterwards to Disconnected.
+)__");
+
+PyDoc_STRVAR(processEvents,
+R"__(processEvents($self, waitForMoreEvents, timeoutMs)
+--
+
+Is responsible for executing all actions/events/etc. (or simply: "events") that are pending in the order they are issued:
+- triggers user's callbacks
+- updates internal states
+- notifies modules
+- handles modules' requests
+The method can optionally wait for more events if no events are queued.
+
+:param bool waitForMoreEvents: if true and no queued events, wait for events to be queued, otherwise process the queued events immediately.
+:param int timeoutMs: wait timeout in milliseconds. If zero, wait indefinitely.
+)__");
+
+PyDoc_STRVAR(getModule,
+R"__(getModule($self, type)
+--
+
+Returns an abstract module if possible for the given type.
+
+:param tvagentapi.Module.Type type: what type of module to create.
+:return module object.
+)__");
+
+PyDoc_STRVAR(setCallbacks,
+R"__(setCallbacks($self, statusChanged=None)
+--
+
+Sets callback to handle changes in connection status.
+
+:param statusChanged: called when the connection status changes
+:type statusChanged: callback(tvagentapi.AgentConnection.Status status)
+)__");
+
+} // namespace DocStrings
+
 PyMethodDef PyAgentConnection_methods[] =
 {
 	{
 		"start",
-		reinterpret_cast<PyCFunction>(PyAgentConnection_start),
+		PyCFunctionCast(PyAgentConnection_start),
 		METH_NOARGS,
-		"start connection"
+		DocStrings::start
 	},
 	{
 		"stop",
-		reinterpret_cast<PyCFunction>(PyAgentConnection_stop),
+		PyCFunctionCast(PyAgentConnection_stop),
 		METH_NOARGS,
-		"stop connection"
+		DocStrings::stop
 	},
 	{
 		"processEvents",
-		reinterpret_cast<PyCFunction>(PyAgentConnection_processEvents),
+		PyCFunctionCast(PyAgentConnection_processEvents),
 		METH_VARARGS | METH_KEYWORDS,
-		"process events"
+		DocStrings::processEvents
 	},
 	{
 		"getModule",
-		reinterpret_cast<PyCFunction>(PyAgentConnection_getModule),
+		PyCFunctionCast(PyAgentConnection_getModule),
 		METH_O,
-		"get module for type"
+		DocStrings::getModule
 	},
 	{
-		"setStatusChangedCallback",
-		reinterpret_cast<PyCFunction>(PyAgentConnection_setStatusChangedCallback),
-		METH_VARARGS,
-		"set status changed callback"
+		"setCallbacks",
+		PyCFunctionCast(PyAgentConnection_setCallbacks),
+		METH_VARARGS | METH_KEYWORDS,
+		DocStrings::setCallbacks
 	},
 
 	{} // Sentinel