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
|
/*
Copyright (c) 2013-2014 Gustav Hartvigsson
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
#ifndef __H_GLOBAL_NOTIFY__
#define __H_GLOBAL_NOTIFY__
#include "defs.h"
#include "Func.h"
BEGIN_DECLS
/** @file
* @defgroup GlobalNotify GlobalNotify
* @addtogroup GlobalNotify
* @{
*
* SSTS provides a system for global notifications. Global notifications are
* like signals, but have global scope, IE: there is only one GlobalNotify
* object that can exist in the system at any point.
*
* It in not possible to directly access the GlobalNotify object, and it's
* structural stability can not be guaranteed.
*
* SSTS does not initialise the the GlobalNotify object until one of it's
* function are run.
*
* @sa
*/
/**
* An opaque object.
* It is not possible to access the data inside this object.
*/
typedef struct GlobalNotify GlobalNotify;
/**
* Notify all subscribers of the to the
*/
void s_global_notify (char * name, spointer user_data);
/**
* Add a new global notification.
*
* @param name The name of the notification.
*
* @return The unique handle of the notification on success.
* @return <0 on fail.
*
* @note
* You can safely dismiss the handle for the notify.
*/
int s_global_notify_add (char * name);
/**
* A convenience method to check if a notify name is already taken.
*
* @param name The notify name to get the handle from.
*
* @return <0 on fail.
* @return The numerical handle of the notify.
*/
int s_global_notify_get_handle (char * name);
/**
* Substribe to a notify using a callback.
*
* @param name The name of the notify to subscribe to.
* @param callback The callback to be triggered when a notify is sent.
*
* @return The unique subscription handle, this is what is used in
* s_global_notify_unsubscribe() to unsubscribe to a notify.
*
* @note
* A notify Callback has to have the following signature:
* <tt> void my_callback (char * name, spointer user_data) </tt>
*/
int s_global_notify_subscribe (char * name, Callback callback);
/**
* Unsubscribe to a notify.
*
* @param name The name of the notify to unsubscribe to.
* @param subscription_id The ID of the subscription.
*/
sboolean s_global_notify_unsubscribe (char * name, int subscription_id);
/** @} */
END_DECLS
#endif
|