polkit-context.h 7.78 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
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 *
 * Copyright (C) 2007 David Zeuthen, <david@fubar.dk>
 *
 * Licensed under the Academic Free License version 2.1
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program 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 General Public License for more details.
 *
 * You should have received a copy of the GNU 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
 *
 **************************************************************************/

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

David Zeuthen's avatar
David Zeuthen committed
30
31
#ifndef POLKIT_CONTEXT_H
#define POLKIT_CONTEXT_H
32

David Zeuthen's avatar
David Zeuthen committed
33
34
35
36
37
38
39
40
41
#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>
42
#include <polkit/polkit-config.h>
43
#include <polkit/polkit-authorization-db.h>
44

45
46
POLKIT_BEGIN_DECLS

David Zeuthen's avatar
David Zeuthen committed
47
48
struct _PolKitContext;
typedef struct _PolKitContext PolKitContext;
49
50
51
52
53
54

/**
 * PolKitContextConfigChangedCB:
 * @pk_context: PolicyKit context
 * @user_data: user data
 *
55
56
57
58
59
 * 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.
 *
60
61
62
 * The user must have set up watches using #polkit_context_set_io_watch_functions
 * for this to work.
 *
63
64
65
66
67
68
69
 * 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.
70
71
 */
typedef void (*PolKitContextConfigChangedCB) (PolKitContext  *pk_context,
72
                                              void           *user_data);
73

74
/**
75
76
77
 * PolKitContextAddIOWatch:
 * @pk_context: the polkit context
 * @fd: the file descriptor to watch
78
 *
79
80
81
82
83
84
85
 * Type for function supplied by the application to integrate a watch
 * on a file descriptor into the applications main loop. The
 * application must call polkit_grant_io_func() when there is data
 * to read from the file descriptor.
 *
 * For glib mainloop, the function will typically look like this:
 *
86
 * <programlisting>
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
 * 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;
 * }
114
 * </programlisting>
115
116
117
 *
 * Returns: 0 if the watch couldn't be set up; otherwise an unique
 * identifier for the watch.
118
 **/
119
typedef int (*PolKitContextAddIOWatch) (PolKitContext *pk_context, int fd);
120
121

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

143

144
145
146
147
148
149
150
151
152
153
154
155
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);
156

157
158
void           polkit_context_force_reload           (PolKitContext                        *pk_context);

159
void           polkit_context_io_func                (PolKitContext *pk_context, int fd);
160

161
PolKitPolicyCache *polkit_context_get_policy_cache   (PolKitContext *pk_context);
162

163
164
165
166
167
168
169
170
171
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);
172

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

175
176
177
PolKitResult polkit_context_is_caller_authorized (PolKitContext         *pk_context,
                                                  PolKitAction          *action,
                                                  PolKitCaller          *caller,
178
                                                  polkit_bool_t          revoke_if_one_shot,
179
                                                  PolKitError          **error);
180
181
182
183

PolKitResult polkit_context_is_session_authorized (PolKitContext         *pk_context,
                                                   PolKitAction          *action,
                                                   PolKitSession         *session,
184
                                                   PolKitError          **error);
185
186
187

PolKitAuthorizationDB *polkit_context_get_authorization_db (PolKitContext *pk_context);

188
189
POLKIT_END_DECLS

David Zeuthen's avatar
David Zeuthen committed
190
#endif /* POLKIT_CONTEXT_H */
191
192