svn_editor.h revision 299742
1/** 2 * @copyright 3 * ==================================================================== 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 * ==================================================================== 21 * @endcopyright 22 * 23 * @file svn_editor.h 24 * @brief Tree editing functions and structures 25 */ 26 27#ifndef SVN_EDITOR_H 28#define SVN_EDITOR_H 29 30#include <apr_pools.h> 31 32#include "svn_types.h" 33#include "svn_error.h" 34#include "svn_io.h" /* for svn_stream_t */ 35#include "svn_delta.h" 36 37#ifdef __cplusplus 38extern "C" { 39#endif /* __cplusplus */ 40 41 42/*** Temporarily private stuff (should move to svn_delta.h when Editor 43 V2 is made public) ***/ 44 45/** Callback to retrieve a node's entire set of properties. This is 46 * needed by the various editor shims in order to effect backwards 47 * compatibility. 48 * 49 * Implementations should set @a *props to the hash of properties 50 * associated with @a path in @a base_revision, allocating that hash 51 * and its contents in @a result_pool, and should use @a scratch_pool 52 * for temporary allocations. 53 * 54 * @a baton is an implementation-specific closure. 55 */ 56typedef svn_error_t *(*svn_delta_fetch_props_func_t)( 57 apr_hash_t **props, 58 void *baton, 59 const char *path, 60 svn_revnum_t base_revision, 61 apr_pool_t *result_pool, 62 apr_pool_t *scratch_pool 63 ); 64 65/** Callback to retrieve a node's kind. This is needed by the various 66 * editor shims in order to effect backwards compatibility. 67 * 68 * Implementations should set @a *kind to the node kind of @a path in 69 * @a base_revision, using @a scratch_pool for temporary allocations. 70 * 71 * @a baton is an implementation-specific closure. 72 */ 73typedef svn_error_t *(*svn_delta_fetch_kind_func_t)( 74 svn_node_kind_t *kind, 75 void *baton, 76 const char *path, 77 svn_revnum_t base_revision, 78 apr_pool_t *scratch_pool 79 ); 80 81/** Callback to fetch the name of a file to use as a delta base. 82 * 83 * Implementations should set @a *filename to the name of a file 84 * suitable for use as a delta base for @a path in @a base_revision 85 * (allocating @a *filename from @a result_pool), or to @c NULL if the 86 * base stream is empty. @a scratch_pool is provided for temporary 87 * allocations. 88 * 89 * @a baton is an implementation-specific closure. 90 */ 91typedef svn_error_t *(*svn_delta_fetch_base_func_t)( 92 const char **filename, 93 void *baton, 94 const char *path, 95 svn_revnum_t base_revision, 96 apr_pool_t *result_pool, 97 apr_pool_t *scratch_pool 98 ); 99 100/** Collection of callbacks used for the shim code. This structure 101 * may grow additional fields in the future. Therefore, always use 102 * svn_delta_shim_callbacks_default() to allocate new instances of it. 103 */ 104typedef struct svn_delta_shim_callbacks_t 105{ 106 svn_delta_fetch_props_func_t fetch_props_func; 107 svn_delta_fetch_kind_func_t fetch_kind_func; 108 svn_delta_fetch_base_func_t fetch_base_func; 109 void *fetch_baton; 110} svn_delta_shim_callbacks_t; 111 112/** Return a collection of default shim functions in @a result_pool. 113 */ 114svn_delta_shim_callbacks_t * 115svn_delta_shim_callbacks_default(apr_pool_t *result_pool); 116 117 118 119/** Transforming trees ("editing"). 120 * 121 * In Subversion, we have a number of occasions where we transform a tree 122 * from one state into another. This process is called "editing" a tree. 123 * 124 * In processing a `commit' command: 125 * - The client examines its working copy data to determine the set of 126 * changes necessary to transform its base tree into the desired target. 127 * - The client networking library delivers that set of changes/operations 128 * across the wire as an equivalent series of network requests (for 129 * example, to svnserve as an ra_svn protocol stream, or to an 130 * Apache httpd server as WebDAV commands) 131 * - The server receives those requests and applies the sequence of 132 * operations on a revision, producing a transaction representing the 133 * desired target. 134 * - The Subversion server then commits the transaction to the filesystem. 135 * 136 * In processing an `update' command, the process is reversed: 137 * - The Subversion server module talks to the filesystem and computes a 138 * set of changes necessary to bring the client's working copy up to date. 139 * - The server serializes this description of changes, and delivers it to 140 * the client. 141 * - The client networking library receives that reply, producing a set 142 * of changes/operations to alter the working copy into the revision 143 * requested by the update command. 144 * - The working copy library applies those operations to the working copy 145 * to align it with the requested update target. 146 * 147 * The series of changes (or operations) necessary to transform a tree from 148 * one state into another is passed between subsystems using this "editor" 149 * interface. The "receiver" edits its tree according to the operations 150 * described by the "driver". 151 * 152 * Note that the driver must have a perfect understanding of the tree which 153 * the receiver will be applying edits upon. There is no room for error here, 154 * and the interface embodies assumptions/requirements that the driver has 155 * about the targeted tree. As a result, this interface is a standardized 156 * mechanism of *describing* those change operations, but the intimate 157 * knowledge between the driver and the receiver implies some level of 158 * coupling between those subsystems. 159 * 160 * The set of changes, and the data necessary to describe it entirely, is 161 * completely unbounded. An addition of one simple 20 GB file might be well 162 * past the available memory of a machine processing these operations. 163 * As a result, the API to describe the changes is designed to be applied 164 * in a sequential (and relatively random-access) model. The operations 165 * can be streamed from the driver to the receiver, resulting in the 166 * receiver editing its tree to the target state defined by the driver. 167 * 168 * 169 * <h3>History</h3> 170 * 171 * Classically, Subversion had a notion of a "tree delta" which could be 172 * passed around as an independent entity. Theory implied this delta was an 173 * entity in its own right, to be used when and where necessary. 174 * Unfortunately, this theory did not work well in practice. The producer 175 * and consumer of these tree deltas were (and are) tightly coupled. As noted 176 * above, the tree delta producer needed to be *totally* aware of the tree 177 * that it needed to edit. So rather than telling the delta consumer how to 178 * edit its tree, the classic #svn_delta_editor_t interface focused 179 * entirely on the tree delta, an intermediate (logical) data structure 180 * which was unusable outside of the particular, coupled pairing of producer 181 * and consumer. This generation of the API forgoes the logical tree delta 182 * entity and directly passes the necessary edits/changes/operations from 183 * the producer to the consumer. In our new parlance, one subsystem "drives" 184 * a set of operations describing the change, and a "receiver" accepts and 185 * applies them to its tree. 186 * 187 * The classic interface was named #svn_delta_editor_t and was described 188 * idiomatically as the "editor interface". This generation of the interface 189 * retains the "editor" name for that reason. All notions of a "tree delta" 190 * structure are no longer part of this interface. 191 * 192 * The old interface was purely vtable-based and used a number of special 193 * editors which could be interposed between the driver and receiver. Those 194 * editors provided cancellation, debugging, and other various operations. 195 * While the "interposition" pattern is still possible with this interface, 196 * the most common functionality (cancellation and debugging) have been 197 * integrated directly into this new editor system. 198 * 199 * 200 * <h3>Implementation Plan</h3> 201 * @note This section can be removed after Ev2 is fully implemented. 202 * 203 * The delta editor is pretty engrained throughout Subversion, so attempting 204 * to replace it in situ is somewhat akin to performing open heart surgery 205 * while the patient is running a marathon. However, a viable plan should 206 * make things a bit easier, and help parallelize the work. 207 * 208 * In short, the following items need to be done: 209 * -# Implement backward compatibility wrappers ("shims") 210 * -# Use shims to update editor consumers to Ev2 211 * -# Update editor producers to drive Ev2 212 * - This will largely involve rewriting the RA layers to accept and 213 * send Ev2 commands 214 * -# Optimize consumers and producers to leverage the features of Ev2 215 * 216 * The shims are largely self-contained, and as of this writing, are almost 217 * complete. They can be released without much ado. However, they do add 218 * <em>significant</em> performance regressions, which make releasing code 219 * which is half-delta-editor and half-Ev2 inadvisable. As such, the updating 220 * of producers and consumers to Ev2 will probably need to wait until 1.9, 221 * though it could be largely parallelized. 222 * 223 * 224 * @defgroup svn_editor The editor interface 225 * @{ 226 */ 227 228/** An abstract object that edits a target tree. 229 * 230 * @note The term "follow" means at any later time in the editor drive. 231 * Terms such as "must", "must not", "required", "shall", "shall not", 232 * "should", "should not", "recommended", "may", and "optional" in this 233 * document are to be interpreted as described in RFC 2119. 234 * 235 * @note The editor objects are *not* reentrant. The receiver should not 236 * directly or indirectly invoke an editor API with the same object unless 237 * it has been marked as explicitly supporting reentrancy during a 238 * receiver's callback. This limitation extends to the cancellation 239 * callback, too. (This limitation is due to the scratch_pool shared by 240 * all callbacks, and cleared after each callback; a reentrant call could 241 * clear the outer call's pool). Note that the code itself is reentrant, so 242 * there is no problem using the APIs on different editor objects. 243 * 244 * \n 245 * <h3>Life-Cycle</h3> 246 * 247 * - @b Create: A receiver uses svn_editor_create() to create an 248 * "empty" svn_editor_t. It cannot be used yet, since it still lacks 249 * actual callback functions. svn_editor_create() sets the 250 * #svn_editor_t's callback baton and scratch pool that the callback 251 * functions receive, as well as a cancellation callback and baton 252 * (see "Cancellation" below). 253 * 254 * - @b Set callbacks: The receiver calls svn_editor_setcb_many() or a 255 * succession of the other svn_editor_setcb_*() functions to tell 256 * #svn_editor_t which functions to call when driven by the various 257 * operations. Callback functions are implemented by the receiver and must 258 * adhere to the @c svn_editor_cb_*_t function types as expected by the 259 * svn_editor_setcb_*() functions. See: \n 260 * svn_editor_cb_many_t \n 261 * svn_editor_setcb_many() \n 262 * or \n 263 * svn_editor_setcb_add_directory() \n 264 * svn_editor_setcb_add_file() \n 265 * svn_editor_setcb_add_symlink() \n 266 * svn_editor_setcb_add_absent() \n 267 * svn_editor_setcb_alter_directory() \n 268 * svn_editor_setcb_alter_file() \n 269 * svn_editor_setcb_alter_symlink() \n 270 * svn_editor_setcb_delete() \n 271 * svn_editor_setcb_copy() \n 272 * svn_editor_setcb_move() \n 273 * svn_editor_setcb_complete() \n 274 * svn_editor_setcb_abort() 275 * 276 * - @b Drive: The driver is provided with the completed #svn_editor_t 277 * instance. (It is typically passed to a generic driving 278 * API, which could receive the driving editor calls over the network 279 * by providing a proxy #svn_editor_t on the remote side.) 280 * The driver invokes the #svn_editor_t instance's callback functions 281 * according to the restrictions defined below, in order to describe the 282 * entire set of operations necessary to transform the receiver's tree 283 * into the desired target. The callbacks can be invoked using the 284 * svn_editor_*() functions, i.e.: \n 285 * svn_editor_add_directory() \n 286 * svn_editor_add_file() \n 287 * svn_editor_add_symlink() \n 288 * svn_editor_add_absent() \n 289 * svn_editor_alter_directory() \n 290 * svn_editor_alter_file() \n 291 * svn_editor_alter_symlink() \n 292 * svn_editor_delete() \n 293 * svn_editor_copy() \n 294 * svn_editor_move() \n 295 * \n\n 296 * Just before each callback invocation is carried out, the @a cancel_func 297 * that was passed to svn_editor_create() is invoked to poll any 298 * external reasons to cancel the sequence of operations. Unless it 299 * overrides the cancellation (denoted by #SVN_ERR_CANCELLED), the driver 300 * aborts the transmission by invoking the svn_editor_abort() callback. 301 * Exceptions to this are calls to svn_editor_complete() and 302 * svn_editor_abort(), which cannot be canceled externally. 303 * 304 * - @b Receive: While the driver invokes operations upon the editor, the 305 * receiver finds its callback functions called with the information 306 * to operate on its tree. Each actual callback function receives those 307 * arguments that the driver passed to the "driving" functions, plus these: 308 * - @a baton: This is the @a editor_baton pointer originally passed to 309 * svn_editor_create(). It may be freely used by the callback 310 * implementation to store information across all callbacks. 311 * - @a scratch_pool: This temporary pool is cleared directly after 312 * each callback returns. See "Pool Usage". 313 * \n\n 314 * If the receiver encounters an error within a callback, it returns an 315 * #svn_error_t*. The driver receives this and aborts transmission. 316 * 317 * - @b Complete/Abort: The driver will end transmission by calling \n 318 * svn_editor_complete() if successful, or \n 319 * svn_editor_abort() if an error or cancellation occurred. 320 * \n\n 321 * 322 * <h3>Driving Order Restrictions</h3> 323 * In order to reduce complexity of callback receivers, the editor callbacks 324 * must be driven in adherence to these rules: 325 * 326 * - If any path is added (with add_*) or deleted/moved, then 327 * an svn_editor_alter_directory() call must be made for its parent 328 * directory with the target/eventual set of children. 329 * 330 * - svn_editor_add_directory() -- Another svn_editor_add_*() call must 331 * follow for each child mentioned in the @a children argument of any 332 * svn_editor_add_directory() call. 333 * 334 * - For each node created with add_*, if its parent was created using 335 * svn_editor_add_directory(), then the new child node MUST have been 336 * mentioned in the @a children parameter of the parent's creation. 337 * This allows the parent directory to properly mark the child as 338 * "incomplete" until the child's add_* call arrives. 339 * 340 * - A path should never be referenced more than once by the add_*, alter_*, 341 * and delete operations (the "Once Rule"). The source path of a copy (and 342 * its children, if a directory) may be copied many times, and are 343 * otherwise subject to the Once Rule. The destination path of a copy 344 * or move may have alter_* operations applied, but not add_* or delete. 345 * If the destination path of a copy or move is a directory, 346 * then its children are subject to the Once Rule. The source path of 347 * a move (and its child paths) may be referenced in add_*, or as the 348 * destination of a copy (where these new or copied nodes are subject 349 * to the Once Rule). 350 * 351 * - The ancestor of an added, copied-here, moved-here, or 352 * modified node may not be deleted. The ancestor may not be moved 353 * (instead: perform the move, *then* the edits). 354 * 355 * - svn_editor_delete() must not be used to replace a path -- i.e. 356 * svn_editor_delete() must not be followed by an svn_editor_add_*() on 357 * the same path, nor by an svn_editor_copy() or svn_editor_move() with 358 * the same path as the copy/move target. 359 * 360 * Instead of a prior delete call, the add/copy/move callbacks should be 361 * called with the @a replaces_rev argument set to the revision number of 362 * the node at this path that is being replaced. Note that the path and 363 * revision number are the key to finding any other information about the 364 * replaced node, like node kind, etc. 365 * @todo say which function(s) to use. 366 * 367 * - svn_editor_delete() must not be used to move a path -- i.e. 368 * svn_editor_delete() must not delete the source path of a previous 369 * svn_editor_copy() call. Instead, svn_editor_move() must be used. 370 * Note: if the desired semantics is one (or more) copies, followed 371 * by a delete... that is fine. It is simply that svn_editor_move() 372 * should be used to describe a semantic move. 373 * 374 * - One of svn_editor_complete() or svn_editor_abort() must be called 375 * exactly once, which must be the final call the driver invokes. 376 * Invoking svn_editor_complete() must imply that the set of changes has 377 * been transmitted completely and without errors, and invoking 378 * svn_editor_abort() must imply that the transformation was not completed 379 * successfully. 380 * 381 * - If any callback invocation (besides svn_editor_complete()) returns 382 * with an error, the driver must invoke svn_editor_abort() and stop 383 * transmitting operations. 384 * \n\n 385 * 386 * <h3>Receiving Restrictions</h3> 387 * 388 * All callbacks must complete their handling of a path before they return. 389 * Since future callbacks will never reference this path again (due to the 390 * Once Rule), the changes can and should be completed. 391 * 392 * This restriction is not recursive -- a directory's children may remain 393 * incomplete until later callback calls are received. 394 * 395 * For example, an svn_editor_add_directory() call during an 'update' 396 * operation will create the directory itself, including its properties, 397 * and will complete any client notification for the directory itself. 398 * The immediate children of the added directory, given in @a children, 399 * will be recorded in the WC as 'incomplete' and will be completed in the 400 * course of the same operation sequence, when the corresponding callbacks 401 * for these items are invoked. 402 * \n\n 403 * 404 * <h3>Timing and State</h3> 405 * The calls made by the driver to alter the state in the receiver are 406 * based on the receiver's *current* state, which includes all prior changes 407 * made during the edit. 408 * 409 * Example: copy A to B; set-props on A; copy A to C. The props on C 410 * should reflect the updated properties of A. 411 * 412 * Example: mv A@N to B; mv C@M to A. The second move cannot be marked as 413 * a "replacing" move since it is not replacing A. The node at A was moved 414 * away. The second operation is simply moving C to the now-empty path 415 * known as A. 416 * 417 * <h3>Paths</h3> 418 * Each driver/receiver implementation of this editor interface must 419 * establish the expected root for all the paths sent and received via 420 * the callbacks' @a relpath arguments. 421 * 422 * For example, during an "update", the driver is the repository, as a 423 * whole. The receiver may have just a portion of that repository. Here, 424 * the receiver could tell the driver which repository URL the working 425 * copy refers to, and thus the driver could send @a relpath arguments 426 * that are relative to the receiver's working copy. 427 * 428 * @note Because the source of a copy may be located *anywhere* in the 429 * repository, editor drives should typically use the repository root 430 * as the negotiated root. This allows the @a src_relpath argument in 431 * svn_editor_copy() to specify any possible source. 432 * \n\n 433 * 434 * <h3>Pool Usage</h3> 435 * The @a result_pool passed to svn_editor_create() is used to allocate 436 * the #svn_editor_t instance, and thus it must not be cleared before the 437 * driver has finished driving the editor. 438 * 439 * The @a scratch_pool passed to each callback invocation is derived from 440 * the @a result_pool that was passed to svn_editor_create(). It is 441 * cleared directly after each single callback invocation. 442 * To allocate memory with a longer lifetime from within a callback 443 * function, you may use your own pool kept in the @a editor_baton. 444 * 445 * The @a scratch_pool passed to svn_editor_create() may be used to help 446 * during construction of the #svn_editor_t instance, but it is assumed to 447 * live only until svn_editor_create() returns. 448 * \n\n 449 * 450 * <h3>Cancellation</h3> 451 * To allow graceful interruption by external events (like a user abort), 452 * svn_editor_create() can be passed an #svn_cancel_func_t that is 453 * polled every time the driver invokes a callback, just before the 454 * actual editor callback implementation is invoked. If this function 455 * decides to return with an error, the driver will receive this error 456 * as if the callback function had returned it, i.e. as the result from 457 * calling any of the driving functions (e.g. svn_editor_add_directory()). 458 * As with any other error, the driver must then invoke svn_editor_abort() 459 * and abort the transformation sequence. See #svn_cancel_func_t. 460 * 461 * The @a cancel_baton argument to svn_editor_create() is passed 462 * unchanged to each poll of @a cancel_func. 463 * 464 * The cancellation function and baton are typically provided by the client 465 * context. 466 * 467 * 468 * @todo ### TODO anything missing? 469 * 470 * @since New in 1.8. 471 */ 472typedef struct svn_editor_t svn_editor_t; 473 474/** The kind of the checksum to be used throughout the #svn_editor_t APIs. 475 * 476 * @note ### This may change before Ev2 is official released, so just like 477 * everything else in this file, please don't rely upon it until then. 478 */ 479#define SVN_EDITOR_CHECKSUM_KIND svn_checksum_sha1 480 481 482/** These function types define the callback functions a tree delta consumer 483 * implements. 484 * 485 * Each of these "receiving" function types matches a "driving" function, 486 * which has the same arguments with these differences: 487 * 488 * - These "receiving" functions have a @a baton argument, which is the 489 * @a editor_baton originally passed to svn_editor_create(), as well as 490 * a @a scratch_pool argument. 491 * 492 * - The "driving" functions have an #svn_editor_t* argument, in order to 493 * call the implementations of the function types defined here that are 494 * registered with the given #svn_editor_t instance. 495 * 496 * Note that any remaining arguments for these function types are explained 497 * in the comment for the "driving" functions. Each function type links to 498 * its corresponding "driver". 499 * 500 * @see svn_editor_t, svn_editor_cb_many_t. 501 * 502 * @defgroup svn_editor_callbacks Editor callback definitions 503 * @{ 504 */ 505 506/** @see svn_editor_add_directory(), svn_editor_t. 507 * @since New in 1.8. 508 */ 509typedef svn_error_t *(*svn_editor_cb_add_directory_t)( 510 void *baton, 511 const char *relpath, 512 const apr_array_header_t *children, 513 apr_hash_t *props, 514 svn_revnum_t replaces_rev, 515 apr_pool_t *scratch_pool); 516 517/** @see svn_editor_add_file(), svn_editor_t. 518 * @since New in 1.8. 519 */ 520typedef svn_error_t *(*svn_editor_cb_add_file_t)( 521 void *baton, 522 const char *relpath, 523 const svn_checksum_t *checksum, 524 svn_stream_t *contents, 525 apr_hash_t *props, 526 svn_revnum_t replaces_rev, 527 apr_pool_t *scratch_pool); 528 529/** @see svn_editor_add_symlink(), svn_editor_t. 530 * @since New in 1.8. 531 */ 532typedef svn_error_t *(*svn_editor_cb_add_symlink_t)( 533 void *baton, 534 const char *relpath, 535 const char *target, 536 apr_hash_t *props, 537 svn_revnum_t replaces_rev, 538 apr_pool_t *scratch_pool); 539 540/** @see svn_editor_add_absent(), svn_editor_t. 541 * @since New in 1.8. 542 */ 543typedef svn_error_t *(*svn_editor_cb_add_absent_t)( 544 void *baton, 545 const char *relpath, 546 svn_node_kind_t kind, 547 svn_revnum_t replaces_rev, 548 apr_pool_t *scratch_pool); 549 550/** @see svn_editor_alter_directory(), svn_editor_t. 551 * @since New in 1.8. 552 */ 553typedef svn_error_t *(*svn_editor_cb_alter_directory_t)( 554 void *baton, 555 const char *relpath, 556 svn_revnum_t revision, 557 const apr_array_header_t *children, 558 apr_hash_t *props, 559 apr_pool_t *scratch_pool); 560 561/** @see svn_editor_alter_file(), svn_editor_t. 562 * @since New in 1.8. 563 */ 564typedef svn_error_t *(*svn_editor_cb_alter_file_t)( 565 void *baton, 566 const char *relpath, 567 svn_revnum_t revision, 568 const svn_checksum_t *checksum, 569 svn_stream_t *contents, 570 apr_hash_t *props, 571 apr_pool_t *scratch_pool); 572 573/** @see svn_editor_alter_symlink(), svn_editor_t. 574 * @since New in 1.8. 575 */ 576typedef svn_error_t *(*svn_editor_cb_alter_symlink_t)( 577 void *baton, 578 const char *relpath, 579 svn_revnum_t revision, 580 const char *target, 581 apr_hash_t *props, 582 apr_pool_t *scratch_pool); 583 584/** @see svn_editor_delete(), svn_editor_t. 585 * @since New in 1.8. 586 */ 587typedef svn_error_t *(*svn_editor_cb_delete_t)( 588 void *baton, 589 const char *relpath, 590 svn_revnum_t revision, 591 apr_pool_t *scratch_pool); 592 593/** @see svn_editor_copy(), svn_editor_t. 594 * @since New in 1.8. 595 */ 596typedef svn_error_t *(*svn_editor_cb_copy_t)( 597 void *baton, 598 const char *src_relpath, 599 svn_revnum_t src_revision, 600 const char *dst_relpath, 601 svn_revnum_t replaces_rev, 602 apr_pool_t *scratch_pool); 603 604/** @see svn_editor_move(), svn_editor_t. 605 * @since New in 1.8. 606 */ 607typedef svn_error_t *(*svn_editor_cb_move_t)( 608 void *baton, 609 const char *src_relpath, 610 svn_revnum_t src_revision, 611 const char *dst_relpath, 612 svn_revnum_t replaces_rev, 613 apr_pool_t *scratch_pool); 614 615/** @see svn_editor_complete(), svn_editor_t. 616 * @since New in 1.8. 617 */ 618typedef svn_error_t *(*svn_editor_cb_complete_t)( 619 void *baton, 620 apr_pool_t *scratch_pool); 621 622/** @see svn_editor_abort(), svn_editor_t. 623 * @since New in 1.8. 624 */ 625typedef svn_error_t *(*svn_editor_cb_abort_t)( 626 void *baton, 627 apr_pool_t *scratch_pool); 628 629/** @} */ 630 631 632/** These functions create an editor instance so that it can be driven. 633 * 634 * @defgroup svn_editor_create Editor creation 635 * @{ 636 */ 637 638/** Allocate an #svn_editor_t instance from @a result_pool, store 639 * @a editor_baton, @a cancel_func and @a cancel_baton in the new instance 640 * and return it in @a editor. 641 * @a scratch_pool is used for temporary allocations (if any). Note that 642 * this is NOT the same @a scratch_pool that is passed to callback functions. 643 * @see svn_editor_t 644 * @since New in 1.8. 645 */ 646svn_error_t * 647svn_editor_create(svn_editor_t **editor, 648 void *editor_baton, 649 svn_cancel_func_t cancel_func, 650 void *cancel_baton, 651 apr_pool_t *result_pool, 652 apr_pool_t *scratch_pool); 653 654 655/** Return an editor's private baton. 656 * 657 * In some cases, the baton is required outside of the callbacks. This 658 * function returns the private baton for use. 659 * 660 * @since New in 1.8. 661 */ 662void * 663svn_editor_get_baton(const svn_editor_t *editor); 664 665 666/** Sets the #svn_editor_cb_add_directory_t callback in @a editor 667 * to @a callback. 668 * @a scratch_pool is used for temporary allocations (if any). 669 * @see also svn_editor_setcb_many(). 670 * @since New in 1.8. 671 */ 672svn_error_t * 673svn_editor_setcb_add_directory(svn_editor_t *editor, 674 svn_editor_cb_add_directory_t callback, 675 apr_pool_t *scratch_pool); 676 677/** Sets the #svn_editor_cb_add_file_t callback in @a editor 678 * to @a callback. 679 * @a scratch_pool is used for temporary allocations (if any). 680 * @see also svn_editor_setcb_many(). 681 * @since New in 1.8. 682 */ 683svn_error_t * 684svn_editor_setcb_add_file(svn_editor_t *editor, 685 svn_editor_cb_add_file_t callback, 686 apr_pool_t *scratch_pool); 687 688/** Sets the #svn_editor_cb_add_symlink_t callback in @a editor 689 * to @a callback. 690 * @a scratch_pool is used for temporary allocations (if any). 691 * @see also svn_editor_setcb_many(). 692 * @since New in 1.8. 693 */ 694svn_error_t * 695svn_editor_setcb_add_symlink(svn_editor_t *editor, 696 svn_editor_cb_add_symlink_t callback, 697 apr_pool_t *scratch_pool); 698 699/** Sets the #svn_editor_cb_add_absent_t callback in @a editor 700 * to @a callback. 701 * @a scratch_pool is used for temporary allocations (if any). 702 * @see also svn_editor_setcb_many(). 703 * @since New in 1.8. 704 */ 705svn_error_t * 706svn_editor_setcb_add_absent(svn_editor_t *editor, 707 svn_editor_cb_add_absent_t callback, 708 apr_pool_t *scratch_pool); 709 710/** Sets the #svn_editor_cb_alter_directory_t callback in @a editor 711 * to @a callback. 712 * @a scratch_pool is used for temporary allocations (if any). 713 * @see also svn_editor_setcb_many(). 714 * @since New in 1.8. 715 */ 716svn_error_t * 717svn_editor_setcb_alter_directory(svn_editor_t *editor, 718 svn_editor_cb_alter_directory_t callback, 719 apr_pool_t *scratch_pool); 720 721/** Sets the #svn_editor_cb_alter_file_t callback in @a editor 722 * to @a callback. 723 * @a scratch_pool is used for temporary allocations (if any). 724 * @see also svn_editor_setcb_many(). 725 * @since New in 1.8. 726 */ 727svn_error_t * 728svn_editor_setcb_alter_file(svn_editor_t *editor, 729 svn_editor_cb_alter_file_t callback, 730 apr_pool_t *scratch_pool); 731 732/** Sets the #svn_editor_cb_alter_symlink_t callback in @a editor 733 * to @a callback. 734 * @a scratch_pool is used for temporary allocations (if any). 735 * @see also svn_editor_setcb_many(). 736 * @since New in 1.8. 737 */ 738svn_error_t * 739svn_editor_setcb_alter_symlink(svn_editor_t *editor, 740 svn_editor_cb_alter_symlink_t callback, 741 apr_pool_t *scratch_pool); 742 743/** Sets the #svn_editor_cb_delete_t callback in @a editor 744 * to @a callback. 745 * @a scratch_pool is used for temporary allocations (if any). 746 * @see also svn_editor_setcb_many(). 747 * @since New in 1.8. 748 */ 749svn_error_t * 750svn_editor_setcb_delete(svn_editor_t *editor, 751 svn_editor_cb_delete_t callback, 752 apr_pool_t *scratch_pool); 753 754/** Sets the #svn_editor_cb_copy_t callback in @a editor 755 * to @a callback. 756 * @a scratch_pool is used for temporary allocations (if any). 757 * @see also svn_editor_setcb_many(). 758 * @since New in 1.8. 759 */ 760svn_error_t * 761svn_editor_setcb_copy(svn_editor_t *editor, 762 svn_editor_cb_copy_t callback, 763 apr_pool_t *scratch_pool); 764 765/** Sets the #svn_editor_cb_move_t callback in @a editor 766 * to @a callback. 767 * @a scratch_pool is used for temporary allocations (if any). 768 * @see also svn_editor_setcb_many(). 769 * @since New in 1.8. 770 */ 771svn_error_t * 772svn_editor_setcb_move(svn_editor_t *editor, 773 svn_editor_cb_move_t callback, 774 apr_pool_t *scratch_pool); 775 776/** Sets the #svn_editor_cb_complete_t callback in @a editor 777 * to @a callback. 778 * @a scratch_pool is used for temporary allocations (if any). 779 * @see also svn_editor_setcb_many(). 780 * @since New in 1.8. 781 */ 782svn_error_t * 783svn_editor_setcb_complete(svn_editor_t *editor, 784 svn_editor_cb_complete_t callback, 785 apr_pool_t *scratch_pool); 786 787/** Sets the #svn_editor_cb_abort_t callback in @a editor 788 * to @a callback. 789 * @a scratch_pool is used for temporary allocations (if any). 790 * @see also svn_editor_setcb_many(). 791 * @since New in 1.8. 792 */ 793svn_error_t * 794svn_editor_setcb_abort(svn_editor_t *editor, 795 svn_editor_cb_abort_t callback, 796 apr_pool_t *scratch_pool); 797 798 799/** Lists a complete set of editor callbacks. 800 * This is a convenience structure. 801 * @see svn_editor_setcb_many(), svn_editor_create(), svn_editor_t. 802 * @since New in 1.8. 803 */ 804typedef struct svn_editor_cb_many_t 805{ 806 svn_editor_cb_add_directory_t cb_add_directory; 807 svn_editor_cb_add_file_t cb_add_file; 808 svn_editor_cb_add_symlink_t cb_add_symlink; 809 svn_editor_cb_add_absent_t cb_add_absent; 810 svn_editor_cb_alter_directory_t cb_alter_directory; 811 svn_editor_cb_alter_file_t cb_alter_file; 812 svn_editor_cb_alter_symlink_t cb_alter_symlink; 813 svn_editor_cb_delete_t cb_delete; 814 svn_editor_cb_copy_t cb_copy; 815 svn_editor_cb_move_t cb_move; 816 svn_editor_cb_complete_t cb_complete; 817 svn_editor_cb_abort_t cb_abort; 818 819} svn_editor_cb_many_t; 820 821/** Sets all the callback functions in @a editor at once, according to the 822 * callback functions stored in @a many. 823 * @a scratch_pool is used for temporary allocations (if any). 824 * @since New in 1.8. 825 */ 826svn_error_t * 827svn_editor_setcb_many(svn_editor_t *editor, 828 const svn_editor_cb_many_t *many, 829 apr_pool_t *scratch_pool); 830 831/** @} */ 832 833 834/** These functions are called by the tree delta driver to edit the target. 835 * 836 * @see svn_editor_t. 837 * 838 * @defgroup svn_editor_drive Driving the editor 839 * @{ 840 */ 841 842/** Drive @a editor's #svn_editor_cb_add_directory_t callback. 843 * 844 * Create a new directory at @a relpath. The immediate parent of @a relpath 845 * is expected to exist. 846 * 847 * For descriptions of @a props and @a replaces_rev, see 848 * svn_editor_add_file(). 849 * 850 * A complete listing of the immediate children of @a relpath that will be 851 * added subsequently is given in @a children. @a children is an array of 852 * const char*s, each giving the basename of an immediate child. It is an 853 * error to pass NULL for @a children; use an empty array to indicate 854 * the new directory will have no children. 855 * 856 * For all restrictions on driving the editor, see #svn_editor_t. 857 */ 858svn_error_t * 859svn_editor_add_directory(svn_editor_t *editor, 860 const char *relpath, 861 const apr_array_header_t *children, 862 apr_hash_t *props, 863 svn_revnum_t replaces_rev); 864 865/** Drive @a editor's #svn_editor_cb_add_file_t callback. 866 * 867 * Create a new file at @a relpath. The immediate parent of @a relpath 868 * is expected to exist. 869 * 870 * The file's contents are specified in @a contents which has a checksum 871 * matching @a checksum. Both values must be non-NULL. 872 * 873 * Set the properties of the new file to @a props, which is an 874 * apr_hash_t holding key-value pairs. Each key is a const char* of a 875 * property name, each value is a const svn_string_t*. If no properties are 876 * being set on the new file, @a props must be the empty hash. It is an 877 * error to pass NULL for @a props. 878 * 879 * If this add is expected to replace a previously existing file, symlink or 880 * directory at @a relpath, the revision number of the node to be replaced 881 * must be given in @a replaces_rev. Otherwise, @a replaces_rev must be 882 * #SVN_INVALID_REVNUM. Note: it is not allowed to call a "delete" followed 883 * by an "add" on the same path. Instead, an "add" with @a replaces_rev set 884 * accordingly MUST be used. 885 * 886 * For all restrictions on driving the editor, see #svn_editor_t. 887 * @since New in 1.8. 888 */ 889svn_error_t * 890svn_editor_add_file(svn_editor_t *editor, 891 const char *relpath, 892 const svn_checksum_t *checksum, 893 svn_stream_t *contents, 894 apr_hash_t *props, 895 svn_revnum_t replaces_rev); 896 897/** Drive @a editor's #svn_editor_cb_add_symlink_t callback. 898 * 899 * Create a new symbolic link at @a relpath, with a link target of @a 900 * target. The immediate parent of @a relpath is expected to exist. 901 * 902 * For descriptions of @a props and @a replaces_rev, see 903 * svn_editor_add_file(). 904 * 905 * For all restrictions on driving the editor, see #svn_editor_t. 906 * @since New in 1.8. 907 */ 908svn_error_t * 909svn_editor_add_symlink(svn_editor_t *editor, 910 const char *relpath, 911 const char *target, 912 apr_hash_t *props, 913 svn_revnum_t replaces_rev); 914 915/** Drive @a editor's #svn_editor_cb_add_absent_t callback. 916 * 917 * Create an "absent" node of kind @a kind at @a relpath. The immediate 918 * parent of @a relpath is expected to exist. 919 * ### TODO @todo explain "absent". 920 * ### JAF: What are the allowed values of 'kind'? 921 * 922 * For a description of @a replaces_rev, see svn_editor_add_file(). 923 * 924 * For all restrictions on driving the editor, see #svn_editor_t. 925 * @since New in 1.8. 926 */ 927svn_error_t * 928svn_editor_add_absent(svn_editor_t *editor, 929 const char *relpath, 930 svn_node_kind_t kind, 931 svn_revnum_t replaces_rev); 932 933/** Drive @a editor's #svn_editor_cb_alter_directory_t callback. 934 * 935 * Alter the properties of the directory at @a relpath. 936 * 937 * @a revision specifies the revision at which the receiver should 938 * expect to find this node. That is, @a relpath at the start of the 939 * whole edit and @a relpath at @a revision must lie within the same 940 * node-rev (aka location history segment). This information may be used 941 * to catch an attempt to alter and out-of-date directory. If the 942 * directory does not have a corresponding revision in the repository 943 * (e.g. it has not yet been committed), then @a revision should be 944 * #SVN_INVALID_REVNUM. 945 * 946 * If any changes to the set of children will be made in the future of 947 * the edit drive, then @a children MUST specify the resulting set of 948 * children. See svn_editor_add_directory() for the format of @a children. 949 * If not changes will be made, then NULL may be specified. 950 * 951 * For a description of @a props, see svn_editor_add_file(). If no changes 952 * to the properties will be made (ie. only future changes to the set of 953 * children), then @a props may be NULL. 954 * 955 * It is an error to pass NULL for both @a children and @a props. 956 * 957 * For all restrictions on driving the editor, see #svn_editor_t. 958 * @since New in 1.8. 959 */ 960svn_error_t * 961svn_editor_alter_directory(svn_editor_t *editor, 962 const char *relpath, 963 svn_revnum_t revision, 964 const apr_array_header_t *children, 965 apr_hash_t *props); 966 967/** Drive @a editor's #svn_editor_cb_alter_file_t callback. 968 * 969 * Alter the properties and/or the contents of the file at @a relpath 970 * with @a revision as its expected revision. See svn_editor_alter_directory() 971 * for more information about @a revision. 972 * 973 * If @a props is non-NULL, then the properties will be applied. 974 * 975 * If @a contents is non-NULL, then the stream will be copied to 976 * the file, and its checksum must match @a checksum (which must also 977 * be non-NULL). If @a contents is NULL, then @a checksum must also 978 * be NULL, and no change will be applied to the file's contents. 979 * 980 * The properties and/or the contents must be changed. It is an error to 981 * pass NULL for @a props, @a checksum, and @a contents. 982 * 983 * For a description of @a checksum and @a contents see 984 * svn_editor_add_file(). This function allows @a props to be NULL, but 985 * the parameter is otherwise described by svn_editor_add_file(). 986 * 987 * For all restrictions on driving the editor, see #svn_editor_t. 988 * @since New in 1.8. 989 */ 990svn_error_t * 991svn_editor_alter_file(svn_editor_t *editor, 992 const char *relpath, 993 svn_revnum_t revision, 994 const svn_checksum_t *checksum, 995 svn_stream_t *contents, 996 apr_hash_t *props); 997 998/** Drive @a editor's #svn_editor_cb_alter_symlink_t callback. 999 * 1000 * Alter the properties and/or the target of the symlink at @a relpath 1001 * with @a revision as its expected revision. See svn_editor_alter_directory() 1002 * for more information about @a revision. 1003 * 1004 * If @a props is non-NULL, then the properties will be applied. 1005 * 1006 * If @a target is non-NULL, then the symlink's target will be updated. 1007 * 1008 * The properties and/or the target must be changed. It is an error to 1009 * pass NULL for @a props and @a target. 1010 * 1011 * This function allows @a props to be NULL, but the parameter is 1012 * otherwise described by svn_editor_add_file(). 1013 * 1014 * For all restrictions on driving the editor, see #svn_editor_t. 1015 * @since New in 1.8. 1016 */ 1017svn_error_t * 1018svn_editor_alter_symlink(svn_editor_t *editor, 1019 const char *relpath, 1020 svn_revnum_t revision, 1021 const char *target, 1022 apr_hash_t *props); 1023 1024/** Drive @a editor's #svn_editor_cb_delete_t callback. 1025 * 1026 * Delete the existing node at @a relpath, expected to be identical to 1027 * revision @a revision of that path. 1028 * 1029 * For all restrictions on driving the editor, see #svn_editor_t. 1030 * @since New in 1.8. 1031 */ 1032svn_error_t * 1033svn_editor_delete(svn_editor_t *editor, 1034 const char *relpath, 1035 svn_revnum_t revision); 1036 1037/** Drive @a editor's #svn_editor_cb_copy_t callback. 1038 * 1039 * Copy the node at @a src_relpath, expected to be identical to revision @a 1040 * src_revision of that path, to @a dst_relpath. 1041 * 1042 * For a description of @a replaces_rev, see svn_editor_add_file(). 1043 * 1044 * @note See the general instructions on paths for this API. Since the 1045 * @a src_relpath argument must generally be able to reference any node 1046 * in the repository, the implication is that the editor's root must be 1047 * the repository root. 1048 * 1049 * For all restrictions on driving the editor, see #svn_editor_t. 1050 * @since New in 1.8. 1051 */ 1052svn_error_t * 1053svn_editor_copy(svn_editor_t *editor, 1054 const char *src_relpath, 1055 svn_revnum_t src_revision, 1056 const char *dst_relpath, 1057 svn_revnum_t replaces_rev); 1058 1059/** Drive @a editor's #svn_editor_cb_move_t callback. 1060 * 1061 * Move the node at @a src_relpath to @a dst_relpath. 1062 * 1063 * @a src_revision specifies the revision at which the receiver should 1064 * expect to find this node. That is, @a src_relpath at the start of 1065 * the whole edit and @a src_relpath at @a src_revision must lie within 1066 * the same node-rev (aka history-segment). This is just like the 1067 * revisions specified to svn_editor_delete(). 1068 * 1069 * For a description of @a replaces_rev, see svn_editor_add_file(). 1070 * 1071 * ### what happens if one side of this move is not "within" the receiver's 1072 * ### set of paths? 1073 * 1074 * For all restrictions on driving the editor, see #svn_editor_t. 1075 * @since New in 1.8. 1076 */ 1077svn_error_t * 1078svn_editor_move(svn_editor_t *editor, 1079 const char *src_relpath, 1080 svn_revnum_t src_revision, 1081 const char *dst_relpath, 1082 svn_revnum_t replaces_rev); 1083 1084/** Drive @a editor's #svn_editor_cb_complete_t callback. 1085 * 1086 * Send word that the edit has been completed successfully. 1087 * 1088 * For all restrictions on driving the editor, see #svn_editor_t. 1089 * @since New in 1.8. 1090 */ 1091svn_error_t * 1092svn_editor_complete(svn_editor_t *editor); 1093 1094/** Drive @a editor's #svn_editor_cb_abort_t callback. 1095 * 1096 * Notify that the edit transmission was not successful. 1097 * ### TODO @todo Shouldn't we add a reason-for-aborting argument? 1098 * 1099 * For all restrictions on driving the editor, see #svn_editor_t. 1100 * @since New in 1.8. 1101 */ 1102svn_error_t * 1103svn_editor_abort(svn_editor_t *editor); 1104 1105/** @} */ 1106 1107/** @} */ 1108 1109/** A temporary API which conditionally inserts a double editor shim 1110 * into the chain of delta editors. Used for testing Editor v2. 1111 * 1112 * Whether or not the shims are inserted is controlled by a compile-time 1113 * option in libsvn_delta/compat.c. 1114 * 1115 * @note The use of these shims and this API will likely cause all kinds 1116 * of performance degredation. (Which is actually a moot point since they 1117 * don't even work properly yet anyway.) 1118 */ 1119svn_error_t * 1120svn_editor__insert_shims(const svn_delta_editor_t **deditor_out, 1121 void **dedit_baton_out, 1122 const svn_delta_editor_t *deditor_in, 1123 void *dedit_baton_in, 1124 const char *repos_root, 1125 const char *base_dir, 1126 svn_delta_shim_callbacks_t *shim_callbacks, 1127 apr_pool_t *result_pool, 1128 apr_pool_t *scratch_pool); 1129 1130 1131#ifdef __cplusplus 1132} 1133#endif /* __cplusplus */ 1134 1135#endif /* SVN_EDITOR_H */ 1136