1 /* 2 WebDAV Class 2 locking operations 3 Copyright (C) 1999-2002, Joe Orton <joe@manyfish.co.uk> 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 BEGIN_NEON_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 char *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 148 /* The ne_lock_using_* functions should be used before dispatching a 149 * request which modify resources. If a lock store has been 150 * registered with the session associated with the request, and locks 151 * are present in the lock store which cover the resources which are 152 * being modified by the request, then the appropriate lock tokens are 153 * submitted in the request headers. */ 154 155 /* Indicate that request 'req' will modify the resource at 'path', and 156 * is an operation of given 'depth'. */ 157 void ne_lock_using_resource(ne_request *req, const char *path, int depth); 158 159 /* Indicate that request 'req' will modify the parent collection of 160 * the resource found at 'path' (for instance when removing the 161 * resource from the collection). */ 162 void ne_lock_using_parent(ne_request *req, const char *path); 163 164 END_NEON_DECLS 165 166 #endif /* NE_LOCKS_H */ 167