added more documents.

removed the obsolete snd_seq_port_subscribe_set_voices().

include/seq.h

@@ -46,13 +46,14 @@ extern "C" {
 /** Sequencer handle */
 typedef struct _snd_seq snd_seq_t;
 
-/** Allocate and initialize array on stack \internal */
+#ifndef DOC_HIDDEN
 #define SND_ALLOCA(type,ptr) \
 do {\
 	assert(ptr);\
 	*ptr = (type##_t *)alloca(type##_sizeof());\
 	memset(*ptr, 0, type##_sizeof());\
 } while (0)
+#endif
 
 /**
  * sequencer opening stream types
@@ -315,7 +316,6 @@ int snd_seq_port_subscribe_get_time_real(const snd_seq_port_subscribe_t *info);
 void snd_seq_port_subscribe_set_sender(snd_seq_port_subscribe_t *info, const snd_seq_addr_t *addr);
 void snd_seq_port_subscribe_set_dest(snd_seq_port_subscribe_t *info, const snd_seq_addr_t *addr);
 void snd_seq_port_subscribe_set_queue(snd_seq_port_subscribe_t *info, int q);
-void snd_seq_port_subscribe_set_voices(snd_seq_port_subscribe_t *info, unsigned int voices);
 void snd_seq_port_subscribe_set_exclusive(snd_seq_port_subscribe_t *info, int val);
 void snd_seq_port_subscribe_set_time_update(snd_seq_port_subscribe_t *info, int val);
 void snd_seq_port_subscribe_set_time_real(snd_seq_port_subscribe_t *info, int val);

include/seqmid.h

@@ -42,6 +42,8 @@ extern "C" {
 /**
  * \brief initialize event record
  * \param ev event record pointer
+ * 
+ * This macro clears the given event record pointer to the default status.
  */
 #define snd_seq_ev_clear(ev) \
 	memset(ev, 0, sizeof(snd_seq_event_t))
@@ -51,6 +53,10 @@ extern "C" {
  * \param ev event record
  * \param c destination client id
  * \param p destination port id
+ *
+ * This macro sets the client and port id numbers to the given event record.
+ *
+ * \sa snd_seq_ev_set_subs()
  */
 #define snd_seq_ev_set_dest(ev,c,p) \
 	((ev)->dest.client = (c), (ev)->dest.port = (p))
@@ -58,6 +64,10 @@ extern "C" {
 /**
  * \brief set broadcasting to subscribers
  * \param ev event record
+ *
+ * This macro sets the destination as the subscribers.
+ *
+ * \sa snd_seq_ev_set_dest()
  */
 #define snd_seq_ev_set_subs(ev) \
 	((ev)->dest.client = SND_SEQ_ADDRESS_SUBSCRIBERS,\
@@ -66,6 +76,10 @@ extern "C" {
 /**
  * \brief set broadcasting to all clients/ports
  * \param ev event record
+ *
+ * This macro sets the destination as the broadcasting.
+ *
+ * \sa snd_seq_ev_set_dest()
  */
 #define snd_seq_ev_set_broadcast(ev) \
 	((ev)->dest.client = SND_SEQ_ADDRESS_BROADCAST,\
@@ -75,6 +89,8 @@ extern "C" {
  * \brief set the source port
  * \param ev event record
  * \param p source port id
+ *
+ * This macro sets the source port id number.
  */
 #define snd_seq_ev_set_source(ev,p) \
 	((ev)->source.port = (p))
@@ -82,6 +98,11 @@ extern "C" {
 /**
  * \brief set direct passing mode (without queued)
  * \param ev event instance
+ *
+ * This macro sets the event to the direct passing mode
+ * to be delivered immediately without queueing.
+ * 
+ * \sa snd_seq_ev_schedule_tick(), snd_seq_ev_schedule_real()
  */
 #define snd_seq_ev_set_direct(ev) \
 	((ev)->queue = SND_SEQ_QUEUE_DIRECT)
@@ -92,6 +113,11 @@ extern "C" {
  * \param q queue id to schedule
  * \param relative relative time-stamp if non-zero
  * \param ttick tick time-stamp to be delivered
+ *
+ * This macro sets the scheduling of the event in the
+ * MIDI tick mode.
+ *
+ * \sa snd_seq_ev_schedule_real(), snd_seq_ev_set_direct()
  */
 #define snd_seq_ev_schedule_tick(ev, q, relative, ttick) \
 	((ev)->flags &= ~(SND_SEQ_TIME_STAMP_MASK | SND_SEQ_TIME_MODE_MASK),\
@@ -106,6 +132,11 @@ extern "C" {
  * \param q queue id to schedule
  * \param relative relative time-stamp if non-zero
  * \param rtime time-stamp to be delivered
+ *
+ * This macro sets the scheduling of the event in the
+ * realtime mode.
+ *
+ * \sa snd_seq_ev_schedule_tick(), snd_seq_ev_set_direct()
  */
 #define snd_seq_ev_schedule_real(ev, q, relative, rtime) \
 	((ev)->flags &= ~(SND_SEQ_TIME_STAMP_MASK | SND_SEQ_TIME_MODE_MASK),\
@@ -128,6 +159,8 @@ extern "C" {
  * \param ev event instance
  *
  * Sets the event length mode as fixed size.
+ *
+ * \sa snd_seq_ev_set_variable(), snd_seq_ev_set_varusr()
  */
 #define snd_seq_ev_set_fixed(ev) \
 	((ev)->flags &= ~SND_SEQ_EVENT_LENGTH_MASK,\
@@ -140,6 +173,8 @@ extern "C" {
  * \param dataptr pointer of the external data
  *
  * Sets the event length mode as variable length and stores the data.
+ *
+ * \sa snd_seq_ev_set_fixed(), snd_seq_ev_set_varusr()
  */
 #define snd_seq_ev_set_variable(ev, datalen, dataptr) \
 	((ev)->flags &= ~SND_SEQ_EVENT_LENGTH_MASK,\
@@ -154,6 +189,8 @@ extern "C" {
  * \param ptr pointer of the external data
  *
  * Sets the event length mode as variable user-space data and stores the data.
+ *
+ * \sa snd_seq_ev_set_fixed(), snd_seq_ev_set_variable()
  */
 #define snd_seq_ev_set_varusr(ev, datalen, dataptr) \
 	((ev)->flags &= ~SND_SEQ_EVENT_LENGTH_MASK,\
@@ -178,6 +215,8 @@ extern "C" {
  * \brief set the start queue event
  * \param ev event record
  * \param q queue id to start
+ *
+ * \sa snd_seq_ev_set_queue_stop(), snd_seq_ev_set_queue_continue()
  */
 #define snd_seq_ev_set_queue_start(ev, q) \
 	snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_START, q, 0)
@@ -186,6 +225,8 @@ extern "C" {
  * \brief set the stop queue event
  * \param ev event record
  * \param q queue id to stop
+ *
+ * \sa snd_seq_ev_set_queue_start(), snd_seq_ev_set_queue_continue()
  */
 #define snd_seq_ev_set_queue_stop(ev, q) \
 	snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_STOP, q, 0)
@@ -194,6 +235,8 @@ extern "C" {
  * \brief set the stop queue event
  * \param ev event record
  * \param q queue id to continue
+ *
+ * \sa snd_seq_ev_set_queue_start(), snd_seq_ev_set_queue_stop()
  */
 #define snd_seq_ev_set_queue_continue(ev, q) \
 	snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_CONTINUE, q, 0)

src/seq/seqmid.c

@@ -40,8 +40,10 @@
  * This function sets up general queue control event and sends it.
  * To send at scheduled time, set the schedule in \a ev.
  * If \a ev is NULL, the event is composed locally and sent immediately
- * to the specified queue.  In any cases, you need to call #snd_seq_drain_event
+ * to the specified queue.  In any cases, you need to call #snd_seq_drain_output()
  * appropriately to feed the event.
+ *
+ * \sa snd_seq_alloc_queue()
  */
 int snd_seq_control_queue(snd_seq_t *seq, int q, int type, int value, snd_seq_event_t *ev)
 {
@@ -65,6 +67,8 @@ int snd_seq_control_queue(snd_seq_t *seq, int q, int type, int value, snd_seq_ev
  * \return the created port number or negative error code
  *
  * Creates a port with the given capability and type bits.
+ *
+ * \sa snd_seq_create_port(), snd_seq_delete_simple_port()
  */
 int snd_seq_create_simple_port(snd_seq_t *seq, const char *name,
 			       unsigned int caps, unsigned int type)
@@ -93,6 +97,8 @@ int snd_seq_create_simple_port(snd_seq_t *seq, const char *name,
  * \param seq sequencer handle
  * \param port port id
  * \return 0 on success or negative error code
+ *
+ * \sa snd_seq_delete_port(), snd_seq_create_simple_port()
  */
 int snd_seq_delete_simple_port(snd_seq_t *seq, int port)
 {
@@ -108,6 +114,8 @@ int snd_seq_delete_simple_port(snd_seq_t *seq, int port)
  *
  * Connect from the given sender client:port to the given destination port in the
  * current client.
+ *
+ * \sa snd_seq_subscribe_port(), snd_seq_disconnect_from()
  */
 int snd_seq_connect_from(snd_seq_t *seq, int myport, int src_client, int src_port)
 {
@@ -132,6 +140,8 @@ int snd_seq_connect_from(snd_seq_t *seq, int myport, int src_client, int src_por
  *
  * Connect from the given receiver port in the current client
  * to the given destination client:port.
+ *
+ * \sa snd_seq_subscribe_port(), snd_seq_disconnect_to()
  */
 int snd_seq_connect_to(snd_seq_t *seq, int myport, int dest_client, int dest_port)
 {
@@ -156,6 +166,8 @@ int snd_seq_connect_to(snd_seq_t *seq, int myport, int dest_client, int dest_por
  *
  * Remove connection from the given sender client:port
  * to the given destination port in the current client.
+ *
+ * \sa snd_seq_unsubscribe_port(), snd_seq_connect_from()
  */
 int snd_seq_disconnect_from(snd_seq_t *seq, int myport, int src_client, int src_port)
 {
@@ -180,6 +192,8 @@ int snd_seq_disconnect_from(snd_seq_t *seq, int myport, int src_client, int src_
  *
  * Remove connection from the given sender client:port
  * to the given destination port in the current client.
+ *
+ * \sa snd_seq_unsubscribe_port(), snd_seq_connect_to()
  */
 int snd_seq_disconnect_to(snd_seq_t *seq, int myport, int dest_client, int dest_port)
 {
@@ -204,6 +218,8 @@ int snd_seq_disconnect_to(snd_seq_t *seq, int myport, int dest_client, int dest_
  * \param seq sequencer handle
  * \param name name string
  * \return 0 on success or negative error code
+ *
+ * \sa snd_seq_set_client_info()
  */
 int snd_seq_set_client_name(snd_seq_t *seq, const char *name)
 {
@@ -221,6 +237,8 @@ int snd_seq_set_client_name(snd_seq_t *seq, const char *name)
  * \param seq sequencer handle
  * \param event_type event type to be added
  * \return 0 on success or negative error code
+ *
+ * \sa snd_seq_set_client_info()
  */
 int snd_seq_set_client_event_filter(snd_seq_t *seq, int event_type)
 {
@@ -239,6 +257,8 @@ int snd_seq_set_client_event_filter(snd_seq_t *seq, int event_type)
  * \param seq sequencer handle
  * \param size output pool size
  * \return 0 on success or negative error code
+ *
+ * \sa snd_seq_set_client_pool()
  */
 int snd_seq_set_client_pool_output(snd_seq_t *seq, size_t size)
 {
@@ -256,6 +276,8 @@ int snd_seq_set_client_pool_output(snd_seq_t *seq, size_t size)
  * \param seq sequencer handle
  * \param size output room size
  * \return 0 on success or negative error code
+ *
+ * \sa snd_seq_set_client_pool()
  */
 int snd_seq_set_client_pool_output_room(snd_seq_t *seq, size_t size)
 {
@@ -273,6 +295,8 @@ int snd_seq_set_client_pool_output_room(snd_seq_t *seq, size_t size)
  * \param seq sequencer handle
  * \param size input pool size
  * \return 0 on success or negative error code
+ *
+ * \sa snd_seq_set_client_pool()
  */
 int snd_seq_set_client_pool_input(snd_seq_t *seq, size_t size)
 {
@@ -289,34 +313,34 @@ int snd_seq_set_client_pool_input(snd_seq_t *seq, size_t size)
  * \brief reset client output pool
  * \param seq sequencer handle
  * \return 0 on success or negative error code
+ *
+ * So far, this works ideically like #snd_seq_drop_output().
  */
 int snd_seq_reset_pool_output(snd_seq_t *seq)
 {
-	struct sndrv_seq_remove_events rmp;
+	return snd_seq_drop_output(seq);
-
-	memset(&rmp, 0, sizeof(rmp));
-	rmp.remove_mode = SNDRV_SEQ_REMOVE_OUTPUT; /* remove all outputs */
-	return snd_seq_remove_events(seq, &rmp);
 }
 
 /**
  * \brief reset client input pool
  * \param seq sequencer handle
  * \return 0 on success or negative error code
+ *
+ * So far, this works ideically like #snd_seq_drop_input().
  */
 int snd_seq_reset_pool_input(snd_seq_t *seq)
 {
-	snd_seq_remove_events_t rmp;
+	return snd_seq_drop_input(seq);
-
-	memset(&rmp, 0, sizeof(rmp));
-	rmp.remove_mode = SNDRV_SEQ_REMOVE_INPUT; /* remove all inputs */
-	return snd_seq_remove_events(seq, &rmp);
 }
 
 /**
- * \brief drain output queue
+ * \brief wait until all events are processed
  * \param seq sequencer handle
  * \return 0 on success or negative error code
+ *
+ * This function waits until all events of this client are processed.
+ *
+ * \sa snd_seq_drain_output()
  */
 int snd_seq_sync_output_queue(snd_seq_t *seq)
 {