dfsm: Add all the missing API reference comments
[bendy-bus:bendy-bus.git] / dfsm / dfsm-output-sequence.c
1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
2 /*
3  * D-Bus Simulator
4  * Copyright (C) Philip Withnall 2012 <philip@tecnocode.co.uk>
5  * 
6  * D-Bus Simulator is free software: you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * D-Bus Simulator is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with D-Bus Simulator.  If not, see <http://www.gnu.org/licenses/>.
18  */
19
20 /**
21  * SECTION:dfsm-output-sequence
22  * @short_description: output sequence interface
23  * @stability: Unstable
24  * @include: dfsm/dfsm-output-sequence.h
25  *
26  * Interface for queuing up actions resulting from the execution of a transition, and then outputting them in order at a later time.
27  */
28
29 #include <glib.h>
30
31 #include "dfsm-output-sequence.h"
32
33 G_DEFINE_INTERFACE (DfsmOutputSequence, dfsm_output_sequence, G_TYPE_OBJECT)
34
35 static void
36 dfsm_output_sequence_default_init (DfsmOutputSequenceInterface *iface)
37 {
38         /* Nothing to see here */
39 }
40
41 /**
42  * dfsm_output_sequence_output:
43  * @self: a #DfsmOutputSequence
44  * @error: a #GError, or %NULL
45  *
46  * Cause all events added to the #DfsmOutputSequence to be processed and acted on, in the order they were added to the sequence. If processing any
47  * event fails, processing is immediately abandoned and @error is set. Any remaining events will not be processed.
48  *
49  * This method must be called at most once per #DfsmOutputSequence instance.
50  */
51 void
52 dfsm_output_sequence_output (DfsmOutputSequence *self, GError **error)
53 {
54         DfsmOutputSequenceInterface *iface;
55         GError *child_error = NULL;
56
57         g_return_if_fail (DFSM_IS_OUTPUT_SEQUENCE (self));
58         g_return_if_fail (error == NULL || *error == NULL);
59
60         iface = DFSM_OUTPUT_SEQUENCE_GET_IFACE (self);
61         g_assert (iface->output != NULL);
62
63         iface->output (self, &child_error);
64
65         if (child_error != NULL) {
66                 g_propagate_error (error, child_error);
67         }
68 }
69
70 /**
71  * dfsm_output_sequence_add_reply:
72  * @self: a #DfsmOutputSequence
73  * @parameters: out parameters from the method invocation
74  *
75  * Add an event to the output sequence to reply to the ongoing method call with return values given as out @parameters.
76  */
77 void
78 dfsm_output_sequence_add_reply (DfsmOutputSequence *self, GVariant *parameters)
79 {
80         DfsmOutputSequenceInterface *iface;
81
82         g_return_if_fail (DFSM_IS_OUTPUT_SEQUENCE (self));
83         g_return_if_fail (parameters != NULL);
84
85         iface = DFSM_OUTPUT_SEQUENCE_GET_IFACE (self);
86         g_assert (iface->add_reply != NULL);
87
88         iface->add_reply (self, parameters);
89 }
90
91 /**
92  * dfsm_output_sequence_add_throw:
93  * @self: a #DfsmOutputSequence
94  * @throw_error: #GError to be thrown
95  *
96  * Add an event to the output sequence to throw the given @throw_error.
97  */
98 void
99 dfsm_output_sequence_add_throw (DfsmOutputSequence *self, GError *throw_error)
100 {
101         DfsmOutputSequenceInterface *iface;
102
103         g_return_if_fail (DFSM_IS_OUTPUT_SEQUENCE (self));
104         g_return_if_fail (throw_error != NULL);
105
106         iface = DFSM_OUTPUT_SEQUENCE_GET_IFACE (self);
107         g_assert (iface->add_throw != NULL);
108
109         iface->add_throw (self, throw_error);
110 }
111
112 /**
113  * dfsm_output_sequence_add_emit:
114  * @self: a #DfsmOutputSequence
115  * @interface_name: name of the D-Bus interface defining @signal_name
116  * @signal_name: name of the D-Bus signal to emit
117  * @parameters: parameters to the signal
118  *
119  * Add an event to the output sequence to emit @signal_name with the given @parameters.
120  */
121 void
122 dfsm_output_sequence_add_emit (DfsmOutputSequence *self, const gchar *interface_name, const gchar *signal_name, GVariant *parameters)
123 {
124         DfsmOutputSequenceInterface *iface;
125
126         g_return_if_fail (DFSM_IS_OUTPUT_SEQUENCE (self));
127         g_return_if_fail (interface_name != NULL && *interface_name != '\0');
128         g_return_if_fail (signal_name != NULL && *signal_name != '\0');
129         g_return_if_fail (parameters != NULL);
130
131         iface = DFSM_OUTPUT_SEQUENCE_GET_IFACE (self);
132         g_assert (iface->add_emit != NULL);
133
134         iface->add_emit (self, interface_name, signal_name, parameters);
135 }