polkit-context.h 8.08 KB
Newer Older
1
2
3
/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 8 -*- */
/***************************************************************************
 *
David Zeuthen's avatar
David Zeuthen committed
4
 * polkit-context.h : PolicyKit context
5
6
7
 *
 * Copyright (C) 2007 David Zeuthen, <david@fubar.dk>
 *
8
9
10
11
12
13
14
 * 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:
15
 *
16
17
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
18
 *
19
20
21
22
23
24
25
26
 * 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.
27
28
29
 *
 **************************************************************************/

30
#if !defined (POLKIT_COMPILATION) && !defined(_POLKIT_INSIDE_POLKIT_H)
David Zeuthen's avatar
David Zeuthen committed
31
#error "Only <polkit/polkit.h> can be included directly, this file may disappear or change contents."
32
33
#endif

David Zeuthen's avatar
David Zeuthen committed
34
35
#ifndef POLKIT_CONTEXT_H
#define POLKIT_CONTEXT_H
36

David Zeuthen's avatar
David Zeuthen committed
37
38
39
40
41
42
43
44
45
#include <polkit/polkit-types.h>
#include <polkit/polkit-error.h>
#include <polkit/polkit-result.h>
#include <polkit/polkit-context.h>
#include <polkit/polkit-action.h>
#include <polkit/polkit-seat.h>
#include <polkit/polkit-session.h>
#include <polkit/polkit-caller.h>
#include <polkit/polkit-policy-cache.h>
46
#include <polkit/polkit-config.h>
47
#include <polkit/polkit-authorization-db.h>
48

49
50
POLKIT_BEGIN_DECLS

David Zeuthen's avatar
David Zeuthen committed
51
52
struct _PolKitContext;
typedef struct _PolKitContext PolKitContext;
53
54
55
56
57
58

/**
 * PolKitContextConfigChangedCB:
 * @pk_context: PolicyKit context
 * @user_data: user data
 *
59
60
61
62
63
 * The type of the callback function for when configuration changes.
 * Mechanisms should use this callback to e.g. reconfigure all
 * permissions / acl's they have set in response to policy decisions
 * made from information provided by PolicyKit.
 *
64
65
66
 * The user must have set up watches using #polkit_context_set_io_watch_functions
 * for this to work.
 *
67
68
69
70
71
72
73
 * Note that this function may be called many times within a short
 * interval due to how file monitoring works if e.g. the user is
 * editing a configuration file (editors typically create back-up
 * files). Mechanisms should use a "cool-off" timer (of, say, one
 * second) to avoid doing many expensive operations (such as
 * reconfiguring all ACL's for all devices) within a very short
 * timeframe.
74
75
 */
typedef void (*PolKitContextConfigChangedCB) (PolKitContext  *pk_context,
76
                                              void           *user_data);
77

78
/**
79
80
81
 * PolKitContextAddIOWatch:
 * @pk_context: the polkit context
 * @fd: the file descriptor to watch
82
 *
83
84
 * Type for function supplied by the application to integrate a watch
 * on a file descriptor into the applications main loop. The
85
 * application must call polkit_context_io_func() when there is data
86
87
88
89
 * to read from the file descriptor.
 *
 * For glib mainloop, the function will typically look like this:
 *
90
 * <programlisting>
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
 * static gboolean
 * io_watch_have_data (GIOChannel *channel, GIOCondition condition, gpointer user_data)
 * {
 *         int fd;
 *         PolKitContext *pk_context = user_data;
 *         fd = g_io_channel_unix_get_fd (channel);
 *         polkit_context_io_func (pk_context, fd);
 *         return TRUE;
 * }
 * 
 * static int 
 * io_add_watch (PolKitContext *pk_context, int fd)
 * {
 *         guint id = 0;
 *         GIOChannel *channel;
 *         channel = g_io_channel_unix_new (fd);
 *         if (channel == NULL)
 *                 goto out;
 *         id = g_io_add_watch (channel, G_IO_IN, io_watch_have_data, pk_context);
 *         if (id == 0) {
 *                 g_io_channel_unref (channel);
 *                 goto out;
 *         }
 *         g_io_channel_unref (channel);
 * out:
 *         return id;
 * }
118
 * </programlisting>
119
120
121
 *
 * Returns: 0 if the watch couldn't be set up; otherwise an unique
 * identifier for the watch.
122
 **/
123
typedef int (*PolKitContextAddIOWatch) (PolKitContext *pk_context, int fd);
124
125

/**
126
127
128
129
 * PolKitContextRemoveIOWatch:
 * @pk_context: the context object
 * @watch_id: the id obtained from using the supplied function
 * of type #PolKitContextAddIOWatch
130
 *
131
132
 * Type for function supplied by the application to remove a watch set
 * up via the supplied function of type #PolKitContextAddIOWatch
133
 *
134
 * For the glib mainloop, the function will typically look like this:
135
 *
136
 * <programlisting>
137
138
139
140
141
 * static void 
 * io_remove_watch (PolKitContext *pk_context, int watch_id)
 * {
 *         g_source_remove (watch_id);
 * }
142
 * </programlisting>
143
144
145
146
 *
 **/
typedef void (*PolKitContextRemoveIOWatch) (PolKitContext *pk_context, int watch_id);

147

148
149
150
151
152
153
154
155
156
157
158
159
PolKitContext *polkit_context_new                    (void);
void           polkit_context_set_config_changed     (PolKitContext                        *pk_context, 
                                                      PolKitContextConfigChangedCB          cb, 
                                                      void                                 *user_data);
void           polkit_context_set_io_watch_functions (PolKitContext                        *pk_context,
                                                      PolKitContextAddIOWatch               io_add_watch_func,
                                                      PolKitContextRemoveIOWatch            io_remove_watch_func);
void           polkit_context_set_load_descriptions  (PolKitContext                        *pk_context);
polkit_bool_t  polkit_context_init                   (PolKitContext                        *pk_context, 
                                                      PolKitError                         **error);
PolKitContext *polkit_context_ref                    (PolKitContext                        *pk_context);
void           polkit_context_unref                  (PolKitContext                        *pk_context);
160

161
162
void           polkit_context_force_reload           (PolKitContext                        *pk_context);

163
void           polkit_context_io_func                (PolKitContext *pk_context, int fd);
164

165
PolKitPolicyCache *polkit_context_get_policy_cache   (PolKitContext *pk_context);
166

167
168
169
170
171
172
173
174
175
POLKIT_GNUC_DEPRECATED
PolKitResult polkit_context_can_session_do_action    (PolKitContext   *pk_context,
                                                      PolKitAction    *action,
                                                      PolKitSession   *session);

POLKIT_GNUC_DEPRECATED 
PolKitResult polkit_context_can_caller_do_action     (PolKitContext   *pk_context,
                                                      PolKitAction    *action,
                                                      PolKitCaller    *caller);
176

David Zeuthen's avatar
David Zeuthen committed
177
PolKitConfig *polkit_context_get_config (PolKitContext *pk_context, PolKitError **error);
178

179
180
181
PolKitResult polkit_context_is_caller_authorized (PolKitContext         *pk_context,
                                                  PolKitAction          *action,
                                                  PolKitCaller          *caller,
182
                                                  polkit_bool_t          revoke_if_one_shot,
183
                                                  PolKitError          **error);
184
185
186
187

PolKitResult polkit_context_is_session_authorized (PolKitContext         *pk_context,
                                                   PolKitAction          *action,
                                                   PolKitSession         *session,
188
                                                   PolKitError          **error);
189
190
191

PolKitAuthorizationDB *polkit_context_get_authorization_db (PolKitContext *pk_context);

192
193
POLKIT_END_DECLS

David Zeuthen's avatar
David Zeuthen committed
194
#endif /* POLKIT_CONTEXT_H */
195
196