Python channel introspection (#68)

2 files changed, 20 insertions, 0 deletions

diff --git a/backends/python.c b/backends/python.c
index bd73a20..b9b6518 100644
--- a/backends/python.c
+++ b/backends/python.c
@@ -112,6 +112,24 @@ static int python_prepend_str(PyObject* list, char* str){
 	return 0;
 }
 
+static PyObject* mmpy_channels(PyObject* self, PyObject* args){
+	size_t u = 0;
+	PyObject* list = NULL;
+	instance* inst = *((instance**) PyModule_GetState(self));
+	python_instance_data* data = (python_instance_data*) inst->impl;
+
+	if(!last_timestamp){
+		LOG("The channels() API will not return usable results before the configuration has been read completely");
+	}
+
+	list = PyList_New(data->channels);
+	for(u = 0; u < data->channels; u++){
+		PyList_SET_ITEM(list, u, PyUnicode_FromString(data->channel[u].name));
+	}
+
+	return list;
+}
+
 static PyObject* mmpy_output(PyObject* self, PyObject* args){
 	instance* inst = *((instance**) PyModule_GetState(self));
 	python_instance_data* data = (python_instance_data*) inst->impl;
@@ -432,6 +450,7 @@ static PyObject* mmpy_init(){
 		{"timestamp", mmpy_timestamp, METH_VARARGS, "Get the core timestamp (in milliseconds)"},
 		{"manage", mmpy_manage_fd, METH_VARARGS, "(Un-)register a socket or file descriptor for notifications"},
 		{"interval", mmpy_interval, METH_VARARGS, "Register or update an interval handler"},
+		{"channels", mmpy_channels, METH_VARARGS, "List currently registered instance channels"},
 		{"cleanup_handler", mmpy_cleanup_handler, METH_VARARGS, "Register or update the instances cleanup handler"},
 		{0}
 	};
diff --git a/backends/python.md b/backends/python.md
index a78d972..2114a08 100644
--- a/backends/python.md
+++ b/backends/python.md
@@ -24,6 +24,7 @@ The `midimonster` module provides the following functions:
 | `timestamp()`			| `print(midimonster.timestamp())`	| Get the internal core timestamp (in milliseconds)	|
 | `interval(function, long)`	| `midimonster.interval(toggle, 100)`	| Register a function to be called periodically. Interval is specified in milliseconds (accurate to 10msec). Calling `interval` with the same function again updates the interval. Specifying the interval as `0` cancels the interval |
 | `manage(function, socket)`	| `midimonster.manage(handler, socket)`	| Register a (connected/listening) socket to the MIDIMonster core. Calls `function(socket)` when the socket is ready to read. Calling this method with `None` as the function argument unregisters the socket. A socket may only have one associated handler |
+| `channels()`			| `midimonster.channels()`		| Fetch a list of all currently known channels on the instance. Note that this function only returns useful data after the configuration has been read completely, i.e. any time after initial startup |
 | `cleanup_handler(function)`	| `midimonster.cleanup_handler(save_all)`| Register a function to be called when the instance is destroyed (on MIDIMonster shutdown). One cleanup handler can be registered per instance. Calling this function when the instance already has a cleanup handler registered replaces the handler, returning the old one. |
 
 When a channel handler executes, calling `midimonster.inputvalue()` for that exact channel returns the previous value,