| 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 */ |