From 0854ef071f73b51ccb0d1eb22c5bf8addf7bc944 Mon Sep 17 00:00:00 2001 From: Takashi Sakamoto Date: Sat, 6 Jun 2020 11:17:32 +0900 Subject: [PATCH] rawmidi; fulfill documentation for ALSARawmidi Signed-off-by: Takashi Sakamoto --- doc/reference/rawmidi/alsarawmidi-docs.xml | 9 +++++++++ src/rawmidi/query.c | 7 +++++++ src/rawmidi/stream-pair.c | 23 ++++++++++++++++++++++ src/rawmidi/substream-info.c | 13 ++++++++++++ src/rawmidi/substream-params.c | 13 ++++++++++++ src/rawmidi/substream-status.c | 12 +++++++++++ 6 files changed, 77 insertions(+) diff --git a/doc/reference/rawmidi/alsarawmidi-docs.xml b/doc/reference/rawmidi/alsarawmidi-docs.xml index 284556c..392bbeb 100644 --- a/doc/reference/rawmidi/alsarawmidi-docs.xml +++ b/doc/reference/rawmidi/alsarawmidi-docs.xml @@ -12,6 +12,15 @@ + + Introduction + This library is designed for applications to manipulate ALSA + Rawmidi character device and operate rawmidi functionality abstracted + as a pair of streams and substream. ALSARawmidiStreamPair represents + the pair of streams. It holds file descriptor and creates GSource for + event dispathing by GLib's GMainContext/GMainLoop. + + ALSARawmidi enumerations diff --git a/src/rawmidi/query.c b/src/rawmidi/query.c index b5670e9..b478278 100644 --- a/src/rawmidi/query.c +++ b/src/rawmidi/query.c @@ -12,6 +12,13 @@ #include +/** + * SECTION: query + * @Title: Global functions in ALSARawmidi + * @Short_description: Global functions available without holding any file + * descriptor + */ + // For error reporting. G_DEFINE_QUARK("alsarawmidi-error", alsarawmidi_error) diff --git a/src/rawmidi/stream-pair.c b/src/rawmidi/stream-pair.c index 218b3cb..41d41cf 100644 --- a/src/rawmidi/stream-pair.c +++ b/src/rawmidi/stream-pair.c @@ -11,6 +11,29 @@ #include #include +/** + * SECTION: stream-pair + * @Title: ALSARawmidiStreamPair + * @Short_description: A GObject-derived object to represent a pair of Rawmidi + * stream. + * + * A #ALSARawmidiStreamPair is a GObject-derived object to represent a pair + * of Rawmidi stream to which substreams are attached. The substream is pointed + * by the combination of the numerical ID of device, subdevice, and direction. + * When the call of alsarawmidi_stream_pair_open() with the combination, + * corresponding substreams are attached to the object. Then the object maintains + * file descriptor till object destruction. The call of + * alsarawmidi_stream_pair_create_source() returns the instance of GSource. Once + * attached to the GSource, GMainContext/GMainLoop is available as event + * dispatcher. The 'handle-messages' GObject signal is emit in the event + * dispatcher to notify the intermediate buffer of capture substream has + * available messages. The call of alsarawmidi_stream_pair_read_from_substream() + * fills the given buffer with the available messages. The call of + * alsarawmidi_stream_pair_write_to_substream() write messages in the given + * buffer into the intermediate buffer of playback substream. The call of + * alsarawmidi_stream_pair_get_substream_status() is available to check the + * space in the intermediate buffer according to direction argument. + */ struct _ALSARawmidiStreamPairPrivate { int fd; char *devnode; diff --git a/src/rawmidi/substream-info.c b/src/rawmidi/substream-info.c index 3e8feec..0c4e47b 100644 --- a/src/rawmidi/substream-info.c +++ b/src/rawmidi/substream-info.c @@ -1,6 +1,19 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "privates.h" +/** + * SECTION: substream-info + * @Title: ALSARawmidiSubstreamInfo + * @Short_description: A GObject-derived object to represent information of + * substream + * + * A #ALSARawmidiSubstreamInfo is a GObject-derived object to represent + * information of substream attached to the pair of streams. The call of + * alsarawmidi_stream_pair_get_substream_info() or + * alsarawmidi_get_substream_info() return the instance of object. + * + * The object wraps 'struct snd_rawmidi_info' in UAPI of Linux sound subsystem. + */ struct _ALSARawmidiSubstreamInfoPrivate { struct snd_rawmidi_info info; }; diff --git a/src/rawmidi/substream-params.c b/src/rawmidi/substream-params.c index bfeb43d..04f900b 100644 --- a/src/rawmidi/substream-params.c +++ b/src/rawmidi/substream-params.c @@ -3,6 +3,19 @@ #include +/** + * SECTION: substream-params + * @Title: ALSARawmidiSubstreamParams + * @Short_description: A GObject-derived object to represent parameters of + * substream. + * + * A #ALSARawmidiSubstreamParams is a GObject-derived object to represent + * parameters of substream attached to the pair of streams. The call of + * alsarawmidi_stream_pair_set_substream_params() requires the instance of + * object. + * + * The object wraps 'struct snd_rawmidi_params' in UAPI of Linux sound subsystem. + */ struct _ALSARawmidiSubstreamParamsPrivate { struct snd_rawmidi_params params; }; diff --git a/src/rawmidi/substream-status.c b/src/rawmidi/substream-status.c index bcebc0a..6dca740 100644 --- a/src/rawmidi/substream-status.c +++ b/src/rawmidi/substream-status.c @@ -1,6 +1,18 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "privates.h" +/** + * SECTION: substream-status + * @Title: ALSARawmidiSubstreamStatus + * @Short_description: A GObject-derived object to represent status of substream + * + * A #ALSARawmidiSubstreamStatus is a GObject-derived object to represent status + * of substream attached to the pair of stream. The call of + * alsarawmidi_stream_pair_get_substream_status() returns the instance of + * object. + * + * The object wraps 'struct snd_rawmidi_status' in UAPI of Linux sound subsystem. + */ struct _ALSARawmidiSubstreamStatusPrivate { struct snd_rawmidi_status status; }; -- 2.47.3