Debian Codegraph @

deps/libneon/src/ne_locks.h

raw
1 /*
2 WebDAV Class 2 locking operations
3 Copyright (C) 1999-2006, Joe Orton <[email protected]>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public
16 License along with this library; if not, write to the Free
17 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
18 MA 02111-1307, USA
19
20 */
21
22 #ifndef NE_LOCKS_H
23 #define NE_LOCKS_H
24
25 #include "ne_request.h" /* for ne_session + ne_request */
26 #include "ne_uri.h" /* for ne_uri */
27
28 NE_BEGIN_DECLS
29
30 /* The scope of a lock */
31 enum ne_lock_scope {
32 ne_lockscope_exclusive,
33 ne_lockscope_shared
34 };
35
36 /* Lock type. Only write locks are defined in RFC2518. */
37 enum ne_lock_type {
38 ne_locktype_write
39 };
40
41 /* A lock object. */
42 struct ne_lock {
43 ne_uri uri;
44 int depth; /* the depth of the lock (NE_DEPTH_*). */
45 enum ne_lock_type type;
46 enum ne_lock_scope scope;
47 char *token; /* the lock token: uniquely identifies this lock. */
48 char *owner; /* string describing the owner of the lock. */
49 long timeout; /* timeout in seconds. (or NE_TIMEOUT_*) */
50 };
51 /* NB: struct ne_lock Would be typedef'ed to ne_lock except lock is
52 * a verb and a noun, so we already have ne_lock the function. Damn
53 * the English language. */
54
55 #define NE_TIMEOUT_INFINITE -1
56 #define NE_TIMEOUT_INVALID -2
57
58 /* Create a depth zero, exclusive write lock, with default timeout
59 * (allowing a server to pick a default). token, owner and uri are
60 * unset. */
61 struct ne_lock *ne_lock_create(void);
62
63 /* HINT: to initialize uri host/port/scheme for the lock's URI, use
64 * ne_fill_server_uri from ne_session.h. */
65
66 /* Deep-copy a lock structure: strdup's any of path, token, owner,
67 * hostport which are set. */
68 struct ne_lock *ne_lock_copy(const struct ne_lock *lock);
69
70 /* Free a lock structure; free's any of any of the URI, token and
71 * owner which are set, but not the lock object itself. */
72 void ne_lock_free(struct ne_lock *lock);
73
74 /* Like ne_lock_free; but free's the lock object itself too. */
75 void ne_lock_destroy(struct ne_lock *lock);
76
77 /* ne_lock_store: an opaque type which is used to store a set of lock
78 * objects. */
79 typedef struct ne_lock_store_s ne_lock_store;
80
81 /* Create a lock store. */
82 ne_lock_store *ne_lockstore_create(void);
83
84 /* Register the lock store 'store' with the HTTP session 'sess': any
85 * operations made using 'sess' which operate on a locked resource,
86 * can use the locks from 'store' if needed. */
87 void ne_lockstore_register(ne_lock_store *store, ne_session *sess);
88
89 /* Destroy a lock store, free'ing any locks remaining inside. */
90 void ne_lockstore_destroy(ne_lock_store *store);
91
92 /* Add a lock to the store: the store then "owns" the lock object, and
93 * you must not free it. The lock MUST have all of:
94 * - a completed URI structure: scheme, host, port, and path all set
95 * - a valid lock token
96 * - a valid depth
97 */
98 void ne_lockstore_add(ne_lock_store *store, struct ne_lock *lock);
99
100 /* Remove given lock object from store: 'lock' MUST point to a lock
101 * object which is known to be in the store. */
102 void ne_lockstore_remove(ne_lock_store *store, struct ne_lock *lock);
103
104 /* Returns the first lock in the lock store, or NULL if the store is
105 * empty. */
106 struct ne_lock *ne_lockstore_first(ne_lock_store *store);
107
108 /* After ne_lockstore_first has been called; returns the next lock in
109 * the lock store, or NULL if there are no more locks stored.
110 * Behaviour is undefined if ne_lockstore_first has not been called on
111 * 'store' since the store was created, or the last time this function
112 * returned NULL for the store.. */
113 struct ne_lock *ne_lockstore_next(ne_lock_store *store);
114
115 /* Find a lock in the store for the given server, and with the given
116 * path. */
117 struct ne_lock *ne_lockstore_findbyuri(ne_lock_store *store,
118 const ne_uri *uri);
119
120 /* Issue a LOCK request for the given lock. Requires that the uri,
121 * depth, type, scope, and timeout members of 'lock' are filled in.
122 * owner and token must be malloc-allocated if not NULL; and may be
123 * free()d by this function. On successful return, lock->token will
124 * contain the lock token. */
125 int ne_lock(ne_session *sess, struct ne_lock *lock);
126
127 /* Issue an UNLOCK request for the given lock */
128 int ne_unlock(ne_session *sess, const struct ne_lock *lock);
129
130 /* Refresh a lock. Updates lock->timeout appropriately. */
131 int ne_lock_refresh(ne_session *sess, struct ne_lock *lock);
132
133 /* Callback for lock discovery. If 'lock' is NULL, something went
134 * wrong performing lockdiscovery for the resource, look at 'status'
135 * for the details.
136 *
137 * If lock is non-NULL, at least lock->uri and lock->token will be
138 * filled in; and status will be NULL. */
139 typedef void (*ne_lock_result)(void *userdata, const struct ne_lock *lock,
140 const ne_uri *uri, const ne_status *status);
141
142 /* Perform lock discovery on the given path. 'result' is called with
143 * the results (possibly >1 times). */
144 int ne_lock_discover(ne_session *sess, const char *path,
145 ne_lock_result result, void *userdata);
146
147 /* The ne_lock_using_* functions should be used before dispatching a
148 * request which modify resources. If a lock store has been
149 * registered with the session associated with the request, and locks
150 * are present in the lock store which cover the resources which are
151 * being modified by the request, then the appropriate lock tokens are
152 * submitted in the request headers. */
153
154 /* Indicate that request 'req' will modify the resource at 'path', and
155 * is an operation of given 'depth'. */
156 void ne_lock_using_resource(ne_request *req, const char *path, int depth);
157
158 /* Indicate that request 'req' will modify the parent collection of
159 * the resource found at 'path' (for instance when removing the
160 * resource from the collection). */
161 void ne_lock_using_parent(ne_request *req, const char *path);
162
163 NE_END_DECLS
164
165 #endif /* NE_LOCKS_H */