← Back to branch summary

~ubuntu-branches/ubuntu/trusty/geis/trusty

« back to all changes in this revision

Viewing changes to libgeis/geis_subscription.h

  • Committer: Package Import Robot
  • Author(s): Chase Douglas
  • Date: 2012-07-30 08:51:42 UTC
  • Revision ID: package-import@ubuntu.com-20120730085142-jrc33ygjvt0ob1wl
Tags: upstream-2.2.11
Import upstream version 2.2.11

Show diffs side-by-side

added added

removed removed

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