1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
/**
* @file geis_subscription.h
* @brief internal Geis subscription modul private interface
*
* Copyright 2010, 2011 Canonical Ltd.
*
* This library is free software; you can redistribute it and/or modify it under
* the terms of the GNU Lesser General Public License as published by the Free
* Software Foundation; either version 3 of the License, or (at your option) any
* later version.
*
* This library is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
* details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
#ifndef GEIS_SUBSCRIPTION_H_
#define GEIS_SUBSCRIPTION_H_
#include <geis/geis.h>
#include "geis_filter.h"
/**
* @defgroup geis_sub_container A Subscription Container
* @{
*/
/**
* A container for subscriptions.
*/
typedef struct _GeisSubBag *GeisSubBag;
typedef GeisSubscription* GeisSubBagIterator;
/**
* Creates a new Geis Subscription container.
*
* @param[in] hint A hint as to how many subscriptions to initially allocate in
* the new container.
*/
GeisSubBag geis_subscription_bag_new(GeisSize size_hint);
/**
* Destroys a Geis Subscription container.
*
* @param[in] bag The bag.
*/
void geis_subscription_bag_delete(GeisSubBag bag);
/**
* Tells how any entires in a Geis Subscription container.
*
* @param[in] bag The bag.
*/
GeisSize geis_subscription_bag_count(GeisSubBag bag);
/**
* Gets an iterator initialized to the first subscription held in a bag.
*
* @param[in] bag The bag.
*/
GeisSubBagIterator geis_subscription_bag_begin(GeisSubBag bag);
/**
* Increments the subscrition bag iterator.
*
* @param[in] bag The bag.
* @param[in] iter The iterator.
*/
GeisSubBagIterator geis_subscription_bag_iterator_next(GeisSubBag bag,
GeisSubBagIterator iter);
/**
* Gets an iterator indicating one-past-the-last sub in a bag.
*
* @param[in] bag The bag.
*/
GeisSubBagIterator geis_subscription_bag_end(GeisSubBag bag);
/**
* Creates a new subscription object in a subscription container.
*
* @param[in] bag The container.
* @param[in] sub The subscription to be added.
*
* @returns the index of the newly inserted subscription
*/
GeisSize geis_subscription_bag_insert(GeisSubBag bag,
GeisSubscription sub);
/**
* Removes a subscription from a subscription container.
*
* @param[in] bag The subscription container.
* @param[in] sub The subscription to be removed.
*/
void geis_subscription_bag_remove(GeisSubBag bag,
GeisSubscription sub);
/**
* Removes all subscriptions from a subscription container.
*
* @param[in] bag The subscription container.
*/
void geis_subscription_bag_empty(GeisSubBag bag);
/**
* Marks all subscriptions in a bag as invalid.
*
* @param[in] bag The subscription container.
*
* See geis_subscription_invalidate.
*/
void geis_subscription_bag_invalidate(GeisSubBag bag);
/**
* Looks for an subscription in an subscription container.
*
* @param[in] bag The bag.
*/
GeisSubscription geis_subscription_bag_find(GeisSubBag bag, GeisInteger sub_id);
/* @} */
/**
* Gets the numvber of filters in a subscirption.
*
* @param[in] sub The subscription.
*/
GeisSize geis_subscription_filter_count(GeisSubscription sub);
/**
* Gets an indicated filter from a subscription.
*
* @param[in] sub The subscription.
* @param[in] index Indicates which filter to retrieve.
*/
GeisFilter geis_subscription_filter(GeisSubscription sub, GeisSize index);
/**
* Gets an iterator initialized to the first filter on a subscription.
*
* @param[in] sub The subscription.
*/
GeisFilterIterator
geis_subscription_filter_begin(GeisSubscription sub);
/**
* Gets an iterator initialized to the one-past-the-last filter on a subscription.
*
* @param[in] sub The subscription.
*/
GeisFilterIterator
geis_subscription_filter_end(GeisSubscription sub);
/**
* Gets the next filter in sequence.
*
* @param[in] sub The subscription.
* @param[in] iter A filter iterator.
*
* @returns an interator initialized to the next filter in sequence in the
* subscription, or an iterator that is equal to geis_subscription_filter_end().
*/
GeisFilterIterator
geis_subscription_filter_next(GeisSubscription sub, GeisFilterIterator iter);
/**
* Invalidates a subscription.
*
* @param[in] sub The subscription.
*
* A subscription becomes invalid when its owning Geis instance has been
* destroyed but the GeisSubscription instance has not. This can occur because
* lifetime of both objects is under external control.
*/
void geis_subscription_invalidate(GeisSubscription sub);
/**
* Sets the operational flags for the subscription.
*
* @param[in] sub The subscription.
* @param[in] flags The subscription flags.
*
* Changes which flags are set during construction of the subscription instance.
* It is inappropriate to change the operational flags of an activated
* subscription.
*
* @retval GEIS_STATUS_SUCCESS Normal successful completion.
* @retval GEIS_STATUS_NOT_SUPPORTED Call made to an activated subcription.
*/
GeisStatus geis_subscription_set_flags(GeisSubscription sub,
GeisSubscriptionFlags flags);
/**
* Gets the operational flags for the subscription.
*
* @param[in] sub The subscription.
*/
GeisSubscriptionFlags geis_subscription_flags(GeisSubscription sub);
/**
* Gets an associated datum from the subscription.
*
* @param[in] sub The subscription.
*/
GeisPointer geis_subscription_pdata(GeisSubscription subscription);
/**
* Sets an associated datum on the subscription.
*
* @param[in] sub The subscription.
* @param[in] data Some data.
*/
void geis_subscription_set_pdata(GeisSubscription subscription, GeisPointer data);
#endif /* GEIS_SUBSCRIPTION_H_ */
|