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_rotate() \n 274 * svn_editor_setcb_complete() \n 275 * svn_editor_setcb_abort() 276 * 277 * - @b Drive: The driver is provided with the completed #svn_editor_t 278 * instance. (It is typically passed to a generic driving 279 * API, which could receive the driving editor calls over the network 280 * by providing a proxy #svn_editor_t on the remote side.) 281 * The driver invokes the #svn_editor_t instance's callback functions 282 * according to the restrictions defined below, in order to describe the 283 * entire set of operations necessary to transform the receiver's tree 284 * into the desired target. The callbacks can be invoked using the 285 * svn_editor_*() functions, i.e.: \n 286 * svn_editor_add_directory() \n 287 * svn_editor_add_file() \n 288 * svn_editor_add_symlink() \n 289 * svn_editor_add_absent() \n 290 * svn_editor_alter_directory() \n 291 * svn_editor_alter_file() \n 292 * svn_editor_alter_symlink() \n 293 * svn_editor_delete() \n 294 * svn_editor_copy() \n 295 * svn_editor_move() \n 296 * svn_editor_rotate() 297 * \n\n 298 * Just before each callback invocation is carried out, the @a cancel_func 299 * that was passed to svn_editor_create() is invoked to poll any 300 * external reasons to cancel the sequence of operations. Unless it 301 * overrides the cancellation (denoted by #SVN_ERR_CANCELLED), the driver 302 * aborts the transmission by invoking the svn_editor_abort() callback. 303 * Exceptions to this are calls to svn_editor_complete() and 304 * svn_editor_abort(), which cannot be canceled externally. 305 * 306 * - @b Receive: While the driver invokes operations upon the editor, the 307 * receiver finds its callback functions called with the information 308 * to operate on its tree. Each actual callback function receives those 309 * arguments that the driver passed to the "driving" functions, plus these: 310 * - @a baton: This is the @a editor_baton pointer originally passed to 311 * svn_editor_create(). It may be freely used by the callback 312 * implementation to store information across all callbacks. 313 * - @a scratch_pool: This temporary pool is cleared directly after 314 * each callback returns. See "Pool Usage". 315 * \n\n 316 * If the receiver encounters an error within a callback, it returns an 317 * #svn_error_t*. The driver receives this and aborts transmission. 318 * 319 * - @b Complete/Abort: The driver will end transmission by calling \n 320 * svn_editor_complete() if successful, or \n 321 * svn_editor_abort() if an error or cancellation occurred. 322 * \n\n 323 * 324 * <h3>Driving Order Restrictions</h3> 325 * In order to reduce complexity of callback receivers, the editor callbacks 326 * must be driven in adherence to these rules: 327 * 328 * - If any path is added (with add_*) or deleted/moved/rotated, then 329 * an svn_editor_alter_directory() call must be made for its parent 330 * directory with the target/eventual set of children. 331 * 332 * - svn_editor_add_directory() -- Another svn_editor_add_*() call must 333 * follow for each child mentioned in the @a children argument of any 334 * svn_editor_add_directory() call. 335 * 336 * - For each node created with add_*, if its parent was created using 337 * svn_editor_add_directory(), then the new child node MUST have been 338 * mentioned in the @a children parameter of the parent's creation. 339 * This allows the parent directory to properly mark the child as 340 * "incomplete" until the child's add_* call arrives. 341 * 342 * - A path should never be referenced more than once by the add_*, alter_*, 343 * and delete operations (the "Once Rule"). The source path of a copy (and 344 * its children, if a directory) may be copied many times, and are 345 * otherwise subject to the Once Rule. The destination path of a copy 346 * or move may have alter_* operations applied, but not add_* or delete. 347 * If the destination path of a copy, move, or rotate is a directory, 348 * then its children are subject to the Once Rule. The source path of 349 * a move (and its child paths) may be referenced in add_*, or as the 350 * destination of a copy (where these new or copied nodes are subject 351 * to the Once Rule). Paths listed in a rotation are both sources and 352 * destinations, so they may not be referenced again in an add_* or a 353 * deletion; these paths may have alter_* operations applied. 354 * 355 * - The ancestor of an added, copied-here, moved-here, rotated, or 356 * modified node may not be deleted. The ancestor may not be moved 357 * (instead: perform the move, *then* the edits). 358 * 359 * - svn_editor_delete() must not be used to replace a path -- i.e. 360 * svn_editor_delete() must not be followed by an svn_editor_add_*() on 361 * the same path, nor by an svn_editor_copy() or svn_editor_move() with 362 * the same path as the copy/move target. 363 * 364 * Instead of a prior delete call, the add/copy/move callbacks should be 365 * called with the @a replaces_rev argument set to the revision number of 366 * the node at this path that is being replaced. Note that the path and 367 * revision number are the key to finding any other information about the 368 * replaced node, like node kind, etc. 369 * @todo say which function(s) to use. 370 * 371 * - svn_editor_delete() must not be used to move a path -- i.e. 372 * svn_editor_delete() must not delete the source path of a previous 373 * svn_editor_copy() call. Instead, svn_editor_move() must be used. 374 * Note: if the desired semantics is one (or more) copies, followed 375 * by a delete... that is fine. It is simply that svn_editor_move() 376 * should be used to describe a semantic move. 377 * 378 * - Paths mentioned in svn_editor_rotate() may have their properties 379 * and contents edited (via alter_* calls) by a previous or later call, 380 * but they may not be subject to a later move, rotate, or deletion. 381 * 382 * - One of svn_editor_complete() or svn_editor_abort() must be called 383 * exactly once, which must be the final call the driver invokes. 384 * Invoking svn_editor_complete() must imply that the set of changes has 385 * been transmitted completely and without errors, and invoking 386 * svn_editor_abort() must imply that the transformation was not completed 387 * successfully. 388 * 389 * - If any callback invocation (besides svn_editor_complete()) returns 390 * with an error, the driver must invoke svn_editor_abort() and stop 391 * transmitting operations. 392 * \n\n 393 * 394 * <h3>Receiving Restrictions</h3> 395 * 396 * All callbacks must complete their handling of a path before they return. 397 * Since future callbacks will never reference this path again (due to the 398 * Once Rule), the changes can and should be completed. 399 * 400 * This restriction is not recursive -- a directory's children may remain 401 * incomplete until later callback calls are received. 402 * 403 * For example, an svn_editor_add_directory() call during an 'update' 404 * operation will create the directory itself, including its properties, 405 * and will complete any client notification for the directory itself. 406 * The immediate children of the added directory, given in @a children, 407 * will be recorded in the WC as 'incomplete' and will be completed in the 408 * course of the same operation sequence, when the corresponding callbacks 409 * for these items are invoked. 410 * \n\n 411 * 412 * <h3>Timing and State</h3> 413 * The calls made by the driver to alter the state in the receiver are 414 * based on the receiver's *current* state, which includes all prior changes 415 * made during the edit. 416 * 417 * Example: copy A to B; set-props on A; copy A to C. The props on C 418 * should reflect the updated properties of A. 419 * 420 * Example: mv A@N to B; mv C@M to A. The second move cannot be marked as 421 * a "replacing" move since it is not replacing A. The node at A was moved 422 * away. The second operation is simply moving C to the now-empty path 423 * known as A. 424 * 425 * <h3>Paths</h3> 426 * Each driver/receiver implementation of this editor interface must 427 * establish the expected root for all the paths sent and received via 428 * the callbacks' @a relpath arguments. 429 * 430 * For example, during an "update", the driver is the repository, as a 431 * whole. The receiver may have just a portion of that repository. Here, 432 * the receiver could tell the driver which repository URL the working 433 * copy refers to, and thus the driver could send @a relpath arguments 434 * that are relative to the receiver's working copy. 435 * 436 * @note Because the source of a copy may be located *anywhere* in the 437 * repository, editor drives should typically use the repository root 438 * as the negotiated root. This allows the @a src_relpath argument in 439 * svn_editor_copy() to specify any possible source. 440 * \n\n 441 * 442 * <h3>Pool Usage</h3> 443 * The @a result_pool passed to svn_editor_create() is used to allocate 444 * the #svn_editor_t instance, and thus it must not be cleared before the 445 * driver has finished driving the editor. 446 * 447 * The @a scratch_pool passed to each callback invocation is derived from 448 * the @a result_pool that was passed to svn_editor_create(). It is 449 * cleared directly after each single callback invocation. 450 * To allocate memory with a longer lifetime from within a callback 451 * function, you may use your own pool kept in the @a editor_baton. 452 * 453 * The @a scratch_pool passed to svn_editor_create() may be used to help 454 * during construction of the #svn_editor_t instance, but it is assumed to 455 * live only until svn_editor_create() returns. 456 * \n\n 457 * 458 * <h3>Cancellation</h3> 459 * To allow graceful interruption by external events (like a user abort), 460 * svn_editor_create() can be passed an #svn_cancel_func_t that is 461 * polled every time the driver invokes a callback, just before the 462 * actual editor callback implementation is invoked. If this function 463 * decides to return with an error, the driver will receive this error 464 * as if the callback function had returned it, i.e. as the result from 465 * calling any of the driving functions (e.g. svn_editor_add_directory()). 466 * As with any other error, the driver must then invoke svn_editor_abort() 467 * and abort the transformation sequence. See #svn_cancel_func_t. 468 * 469 * The @a cancel_baton argument to svn_editor_create() is passed 470 * unchanged to each poll of @a cancel_func. 471 * 472 * The cancellation function and baton are typically provided by the client 473 * context. 474 * 475 * 476 * @todo ### TODO anything missing? 477 * 478 * @since New in 1.8. 479 */ 480typedef struct svn_editor_t svn_editor_t; 481 482/** The kind of the checksum to be used throughout the #svn_editor_t APIs. 483 * 484 * @note ### This may change before Ev2 is official released, so just like 485 * everything else in this file, please don't rely upon it until then. 486 */ 487#define SVN_EDITOR_CHECKSUM_KIND svn_checksum_sha1 488 489 490/** These function types define the callback functions a tree delta consumer 491 * implements. 492 * 493 * Each of these "receiving" function types matches a "driving" function, 494 * which has the same arguments with these differences: 495 * 496 * - These "receiving" functions have a @a baton argument, which is the 497 * @a editor_baton originally passed to svn_editor_create(), as well as 498 * a @a scratch_pool argument. 499 * 500 * - The "driving" functions have an #svn_editor_t* argument, in order to 501 * call the implementations of the function types defined here that are 502 * registered with the given #svn_editor_t instance. 503 * 504 * Note that any remaining arguments for these function types are explained 505 * in the comment for the "driving" functions. Each function type links to 506 * its corresponding "driver". 507 * 508 * @see svn_editor_t, svn_editor_cb_many_t. 509 * 510 * @defgroup svn_editor_callbacks Editor callback definitions 511 * @{ 512 */ 513 514/** @see svn_editor_add_directory(), svn_editor_t. 515 * @since New in 1.8. 516 */ 517typedef svn_error_t *(*svn_editor_cb_add_directory_t)( 518 void *baton, 519 const char *relpath, 520 const apr_array_header_t *children, 521 apr_hash_t *props, 522 svn_revnum_t replaces_rev, 523 apr_pool_t *scratch_pool); 524 525/** @see svn_editor_add_file(), svn_editor_t. 526 * @since New in 1.8. 527 */ 528typedef svn_error_t *(*svn_editor_cb_add_file_t)( 529 void *baton, 530 const char *relpath, 531 const svn_checksum_t *checksum, 532 svn_stream_t *contents, 533 apr_hash_t *props, 534 svn_revnum_t replaces_rev, 535 apr_pool_t *scratch_pool); 536 537/** @see svn_editor_add_symlink(), svn_editor_t. 538 * @since New in 1.8. 539 */ 540typedef svn_error_t *(*svn_editor_cb_add_symlink_t)( 541 void *baton, 542 const char *relpath, 543 const char *target, 544 apr_hash_t *props, 545 svn_revnum_t replaces_rev, 546 apr_pool_t *scratch_pool); 547 548/** @see svn_editor_add_absent(), svn_editor_t. 549 * @since New in 1.8. 550 */ 551typedef svn_error_t *(*svn_editor_cb_add_absent_t)( 552 void *baton, 553 const char *relpath, 554 svn_node_kind_t kind, 555 svn_revnum_t replaces_rev, 556 apr_pool_t *scratch_pool); 557 558/** @see svn_editor_alter_directory(), svn_editor_t. 559 * @since New in 1.8. 560 */ 561typedef svn_error_t *(*svn_editor_cb_alter_directory_t)( 562 void *baton, 563 const char *relpath, 564 svn_revnum_t revision, 565 const apr_array_header_t *children, 566 apr_hash_t *props, 567 apr_pool_t *scratch_pool); 568 569/** @see svn_editor_alter_file(), svn_editor_t. 570 * @since New in 1.8. 571 */ 572typedef svn_error_t *(*svn_editor_cb_alter_file_t)( 573 void *baton, 574 const char *relpath, 575 svn_revnum_t revision, 576 apr_hash_t *props, 577 const svn_checksum_t *checksum, 578 svn_stream_t *contents, 579 apr_pool_t *scratch_pool); 580 581/** @see svn_editor_alter_symlink(), svn_editor_t. 582 * @since New in 1.8. 583 */ 584typedef svn_error_t *(*svn_editor_cb_alter_symlink_t)( 585 void *baton, 586 const char *relpath, 587 svn_revnum_t revision, 588 apr_hash_t *props, 589 const char *target, 590 apr_pool_t *scratch_pool); 591 592/** @see svn_editor_delete(), svn_editor_t. 593 * @since New in 1.8. 594 */ 595typedef svn_error_t *(*svn_editor_cb_delete_t)( 596 void *baton, 597 const char *relpath, 598 svn_revnum_t revision, 599 apr_pool_t *scratch_pool); 600 601/** @see svn_editor_copy(), svn_editor_t. 602 * @since New in 1.8. 603 */ 604typedef svn_error_t *(*svn_editor_cb_copy_t)( 605 void *baton, 606 const char *src_relpath, 607 svn_revnum_t src_revision, 608 const char *dst_relpath, 609 svn_revnum_t replaces_rev, 610 apr_pool_t *scratch_pool); 611 612/** @see svn_editor_move(), svn_editor_t. 613 * @since New in 1.8. 614 */ 615typedef svn_error_t *(*svn_editor_cb_move_t)( 616 void *baton, 617 const char *src_relpath, 618 svn_revnum_t src_revision, 619 const char *dst_relpath, 620 svn_revnum_t replaces_rev, 621 apr_pool_t *scratch_pool); 622 623/** @see svn_editor_rotate(), svn_editor_t. 624 * @since New in 1.8. 625 */ 626typedef svn_error_t *(*svn_editor_cb_rotate_t)( 627 void *baton, 628 const apr_array_header_t *relpaths, 629 const apr_array_header_t *revisions, 630 apr_pool_t *scratch_pool); 631 632/** @see svn_editor_complete(), svn_editor_t. 633 * @since New in 1.8. 634 */ 635typedef svn_error_t *(*svn_editor_cb_complete_t)( 636 void *baton, 637 apr_pool_t *scratch_pool); 638 639/** @see svn_editor_abort(), svn_editor_t. 640 * @since New in 1.8. 641 */ 642typedef svn_error_t *(*svn_editor_cb_abort_t)( 643 void *baton, 644 apr_pool_t *scratch_pool); 645 646/** @} */ 647 648 649/** These functions create an editor instance so that it can be driven. 650 * 651 * @defgroup svn_editor_create Editor creation 652 * @{ 653 */ 654 655/** Allocate an #svn_editor_t instance from @a result_pool, store 656 * @a editor_baton, @a cancel_func and @a cancel_baton in the new instance 657 * and return it in @a editor. 658 * @a scratch_pool is used for temporary allocations (if any). Note that 659 * this is NOT the same @a scratch_pool that is passed to callback functions. 660 * @see svn_editor_t 661 * @since New in 1.8. 662 */ 663svn_error_t * 664svn_editor_create(svn_editor_t **editor, 665 void *editor_baton, 666 svn_cancel_func_t cancel_func, 667 void *cancel_baton, 668 apr_pool_t *result_pool, 669 apr_pool_t *scratch_pool); 670 671 672/** Return an editor's private baton. 673 * 674 * In some cases, the baton is required outside of the callbacks. This 675 * function returns the private baton for use. 676 * 677 * @since New in 1.8. 678 */ 679void * 680svn_editor_get_baton(const svn_editor_t *editor); 681 682 683/** Sets the #svn_editor_cb_add_directory_t callback in @a editor 684 * to @a callback. 685 * @a scratch_pool is used for temporary allocations (if any). 686 * @see also svn_editor_setcb_many(). 687 * @since New in 1.8. 688 */ 689svn_error_t * 690svn_editor_setcb_add_directory(svn_editor_t *editor, 691 svn_editor_cb_add_directory_t callback, 692 apr_pool_t *scratch_pool); 693 694/** Sets the #svn_editor_cb_add_file_t callback in @a editor 695 * to @a callback. 696 * @a scratch_pool is used for temporary allocations (if any). 697 * @see also svn_editor_setcb_many(). 698 * @since New in 1.8. 699 */ 700svn_error_t * 701svn_editor_setcb_add_file(svn_editor_t *editor, 702 svn_editor_cb_add_file_t callback, 703 apr_pool_t *scratch_pool); 704 705/** Sets the #svn_editor_cb_add_symlink_t callback in @a editor 706 * to @a callback. 707 * @a scratch_pool is used for temporary allocations (if any). 708 * @see also svn_editor_setcb_many(). 709 * @since New in 1.8. 710 */ 711svn_error_t * 712svn_editor_setcb_add_symlink(svn_editor_t *editor, 713 svn_editor_cb_add_symlink_t callback, 714 apr_pool_t *scratch_pool); 715 716/** Sets the #svn_editor_cb_add_absent_t callback in @a editor 717 * to @a callback. 718 * @a scratch_pool is used for temporary allocations (if any). 719 * @see also svn_editor_setcb_many(). 720 * @since New in 1.8. 721 */ 722svn_error_t * 723svn_editor_setcb_add_absent(svn_editor_t *editor, 724 svn_editor_cb_add_absent_t callback, 725 apr_pool_t *scratch_pool); 726 727/** Sets the #svn_editor_cb_alter_directory_t callback in @a editor 728 * to @a callback. 729 * @a scratch_pool is used for temporary allocations (if any). 730 * @see also svn_editor_setcb_many(). 731 * @since New in 1.8. 732 */ 733svn_error_t * 734svn_editor_setcb_alter_directory(svn_editor_t *editor, 735 svn_editor_cb_alter_directory_t callback, 736 apr_pool_t *scratch_pool); 737 738/** Sets the #svn_editor_cb_alter_file_t callback in @a editor 739 * to @a callback. 740 * @a scratch_pool is used for temporary allocations (if any). 741 * @see also svn_editor_setcb_many(). 742 * @since New in 1.8. 743 */ 744svn_error_t * 745svn_editor_setcb_alter_file(svn_editor_t *editor, 746 svn_editor_cb_alter_file_t callback, 747 apr_pool_t *scratch_pool); 748 749/** Sets the #svn_editor_cb_alter_symlink_t callback in @a editor 750 * to @a callback. 751 * @a scratch_pool is used for temporary allocations (if any). 752 * @see also svn_editor_setcb_many(). 753 * @since New in 1.8. 754 */ 755svn_error_t * 756svn_editor_setcb_alter_symlink(svn_editor_t *editor, 757 svn_editor_cb_alter_symlink_t callback, 758 apr_pool_t *scratch_pool); 759 760/** Sets the #svn_editor_cb_delete_t callback in @a editor 761 * to @a callback. 762 * @a scratch_pool is used for temporary allocations (if any). 763 * @see also svn_editor_setcb_many(). 764 * @since New in 1.8. 765 */ 766svn_error_t * 767svn_editor_setcb_delete(svn_editor_t *editor, 768 svn_editor_cb_delete_t callback, 769 apr_pool_t *scratch_pool); 770 771/** Sets the #svn_editor_cb_copy_t callback in @a editor 772 * to @a callback. 773 * @a scratch_pool is used for temporary allocations (if any). 774 * @see also svn_editor_setcb_many(). 775 * @since New in 1.8. 776 */ 777svn_error_t * 778svn_editor_setcb_copy(svn_editor_t *editor, 779 svn_editor_cb_copy_t callback, 780 apr_pool_t *scratch_pool); 781 782/** Sets the #svn_editor_cb_move_t callback in @a editor 783 * to @a callback. 784 * @a scratch_pool is used for temporary allocations (if any). 785 * @see also svn_editor_setcb_many(). 786 * @since New in 1.8. 787 */ 788svn_error_t * 789svn_editor_setcb_move(svn_editor_t *editor, 790 svn_editor_cb_move_t callback, 791 apr_pool_t *scratch_pool); 792 793/** Sets the #svn_editor_cb_rotate_t callback in @a editor 794 * to @a callback. 795 * @a scratch_pool is used for temporary allocations (if any). 796 * @see also svn_editor_setcb_many(). 797 * @since New in 1.8. 798 */ 799svn_error_t * 800svn_editor_setcb_rotate(svn_editor_t *editor, 801 svn_editor_cb_rotate_t callback, 802 apr_pool_t *scratch_pool); 803 804/** Sets the #svn_editor_cb_complete_t callback in @a editor 805 * to @a callback. 806 * @a scratch_pool is used for temporary allocations (if any). 807 * @see also svn_editor_setcb_many(). 808 * @since New in 1.8. 809 */ 810svn_error_t * 811svn_editor_setcb_complete(svn_editor_t *editor, 812 svn_editor_cb_complete_t callback, 813 apr_pool_t *scratch_pool); 814 815/** Sets the #svn_editor_cb_abort_t callback in @a editor 816 * to @a callback. 817 * @a scratch_pool is used for temporary allocations (if any). 818 * @see also svn_editor_setcb_many(). 819 * @since New in 1.8. 820 */ 821svn_error_t * 822svn_editor_setcb_abort(svn_editor_t *editor, 823 svn_editor_cb_abort_t callback, 824 apr_pool_t *scratch_pool); 825 826 827/** Lists a complete set of editor callbacks. 828 * This is a convenience structure. 829 * @see svn_editor_setcb_many(), svn_editor_create(), svn_editor_t. 830 * @since New in 1.8. 831 */ 832typedef struct svn_editor_cb_many_t 833{ 834 svn_editor_cb_add_directory_t cb_add_directory; 835 svn_editor_cb_add_file_t cb_add_file; 836 svn_editor_cb_add_symlink_t cb_add_symlink; 837 svn_editor_cb_add_absent_t cb_add_absent; 838 svn_editor_cb_alter_directory_t cb_alter_directory; 839 svn_editor_cb_alter_file_t cb_alter_file; 840 svn_editor_cb_alter_symlink_t cb_alter_symlink; 841 svn_editor_cb_delete_t cb_delete; 842 svn_editor_cb_copy_t cb_copy; 843 svn_editor_cb_move_t cb_move; 844 svn_editor_cb_rotate_t cb_rotate; 845 svn_editor_cb_complete_t cb_complete; 846 svn_editor_cb_abort_t cb_abort; 847 848} svn_editor_cb_many_t; 849 850/** Sets all the callback functions in @a editor at once, according to the 851 * callback functions stored in @a many. 852 * @a scratch_pool is used for temporary allocations (if any). 853 * @since New in 1.8. 854 */ 855svn_error_t * 856svn_editor_setcb_many(svn_editor_t *editor, 857 const svn_editor_cb_many_t *many, 858 apr_pool_t *scratch_pool); 859 860/** @} */ 861 862 863/** These functions are called by the tree delta driver to edit the target. 864 * 865 * @see svn_editor_t. 866 * 867 * @defgroup svn_editor_drive Driving the editor 868 * @{ 869 */ 870 871/** Drive @a editor's #svn_editor_cb_add_directory_t callback. 872 * 873 * Create a new directory at @a relpath. The immediate parent of @a relpath 874 * is expected to exist. 875 * 876 * For descriptions of @a props and @a replaces_rev, see 877 * svn_editor_add_file(). 878 * 879 * A complete listing of the immediate children of @a relpath that will be 880 * added subsequently is given in @a children. @a children is an array of 881 * const char*s, each giving the basename of an immediate child. It is an 882 * error to pass NULL for @a children; use an empty array to indicate 883 * the new directory will have no children. 884 * 885 * For all restrictions on driving the editor, see #svn_editor_t. 886 */ 887svn_error_t * 888svn_editor_add_directory(svn_editor_t *editor, 889 const char *relpath, 890 const apr_array_header_t *children, 891 apr_hash_t *props, 892 svn_revnum_t replaces_rev); 893 894/** Drive @a editor's #svn_editor_cb_add_file_t callback. 895 * 896 * Create a new file at @a relpath. The immediate parent of @a relpath 897 * is expected to exist. 898 * 899 * The file's contents are specified in @a contents which has a checksum 900 * matching @a checksum. Both values must be non-NULL. 901 * 902 * Set the properties of the new file to @a props, which is an 903 * apr_hash_t holding key-value pairs. Each key is a const char* of a 904 * property name, each value is a const svn_string_t*. If no properties are 905 * being set on the new file, @a props must be the empty hash. It is an 906 * error to pass NULL for @a props. 907 * 908 * If this add is expected to replace a previously existing file, symlink or 909 * directory at @a relpath, the revision number of the node to be replaced 910 * must be given in @a replaces_rev. Otherwise, @a replaces_rev must be 911 * #SVN_INVALID_REVNUM. Note: it is not allowed to call a "delete" followed 912 * by an "add" on the same path. Instead, an "add" with @a replaces_rev set 913 * accordingly MUST be used. 914 * 915 * For all restrictions on driving the editor, see #svn_editor_t. 916 * @since New in 1.8. 917 */ 918svn_error_t * 919svn_editor_add_file(svn_editor_t *editor, 920 const char *relpath, 921 const svn_checksum_t *checksum, 922 svn_stream_t *contents, 923 apr_hash_t *props, 924 svn_revnum_t replaces_rev); 925 926/** Drive @a editor's #svn_editor_cb_add_symlink_t callback. 927 * 928 * Create a new symbolic link at @a relpath, with a link target of @a 929 * target. The immediate parent of @a relpath is expected to exist. 930 * 931 * For descriptions of @a props and @a replaces_rev, see 932 * svn_editor_add_file(). 933 * 934 * For all restrictions on driving the editor, see #svn_editor_t. 935 * @since New in 1.8. 936 */ 937svn_error_t * 938svn_editor_add_symlink(svn_editor_t *editor, 939 const char *relpath, 940 const char *target, 941 apr_hash_t *props, 942 svn_revnum_t replaces_rev); 943 944/** Drive @a editor's #svn_editor_cb_add_absent_t callback. 945 * 946 * Create an "absent" node of kind @a kind at @a relpath. The immediate 947 * parent of @a relpath is expected to exist. 948 * ### TODO @todo explain "absent". 949 * ### JAF: What are the allowed values of 'kind'? 950 * 951 * For a description of @a replaces_rev, see svn_editor_add_file(). 952 * 953 * For all restrictions on driving the editor, see #svn_editor_t. 954 * @since New in 1.8. 955 */ 956svn_error_t * 957svn_editor_add_absent(svn_editor_t *editor, 958 const char *relpath, 959 svn_node_kind_t kind, 960 svn_revnum_t replaces_rev); 961 962/** Drive @a editor's #svn_editor_cb_alter_directory_t callback. 963 * 964 * Alter the properties of the directory at @a relpath. 965 * 966 * @a revision specifies the revision at which the receiver should 967 * expect to find this node. That is, @a relpath at the start of the 968 * whole edit and @a relpath at @a revision must lie within the same 969 * node-rev (aka location history segment). This information may be used 970 * to catch an attempt to alter and out-of-date directory. If the 971 * directory does not have a corresponding revision in the repository 972 * (e.g. it has not yet been committed), then @a revision should be 973 * #SVN_INVALID_REVNUM. 974 * 975 * If any changes to the set of children will be made in the future of 976 * the edit drive, then @a children MUST specify the resulting set of 977 * children. See svn_editor_add_directory() for the format of @a children. 978 * If not changes will be made, then NULL may be specified. 979 * 980 * For a description of @a props, see svn_editor_add_file(). If no changes 981 * to the properties will be made (ie. only future changes to the set of 982 * children), then @a props may be NULL. 983 * 984 * It is an error to pass NULL for both @a children and @a props. 985 * 986 * For all restrictions on driving the editor, see #svn_editor_t. 987 * @since New in 1.8. 988 */ 989svn_error_t * 990svn_editor_alter_directory(svn_editor_t *editor, 991 const char *relpath, 992 svn_revnum_t revision, 993 const apr_array_header_t *children, 994 apr_hash_t *props); 995 996/** Drive @a editor's #svn_editor_cb_alter_file_t callback. 997 * 998 * Alter the properties and/or the contents of the file at @a relpath 999 * with @a revision as its expected revision. See svn_editor_alter_directory() 1000 * for more information about @a revision. 1001 * 1002 * If @a props is non-NULL, then the properties will be applied. 1003 * 1004 * If @a contents is non-NULL, then the stream will be copied to 1005 * the file, and its checksum must match @a checksum (which must also 1006 * be non-NULL). If @a contents is NULL, then @a checksum must also 1007 * be NULL, and no change will be applied to the file's contents. 1008 * 1009 * The properties and/or the contents must be changed. It is an error to 1010 * pass NULL for @a props, @a checksum, and @a contents. 1011 * 1012 * For a description of @a checksum and @a contents see 1013 * svn_editor_add_file(). This function allows @a props to be NULL, but 1014 * the parameter is otherwise described by svn_editor_add_file(). 1015 * 1016 * For all restrictions on driving the editor, see #svn_editor_t. 1017 * @since New in 1.8. 1018 */ 1019svn_error_t * 1020svn_editor_alter_file(svn_editor_t *editor, 1021 const char *relpath, 1022 svn_revnum_t revision, 1023 apr_hash_t *props, 1024 const svn_checksum_t *checksum, 1025 svn_stream_t *contents); 1026 1027/** Drive @a editor's #svn_editor_cb_alter_symlink_t callback. 1028 * 1029 * Alter the properties and/or the target of the symlink at @a relpath 1030 * with @a revision as its expected revision. See svn_editor_alter_directory() 1031 * for more information about @a revision. 1032 * 1033 * If @a props is non-NULL, then the properties will be applied. 1034 * 1035 * If @a target is non-NULL, then the symlink's target will be updated. 1036 * 1037 * The properties and/or the target must be changed. It is an error to 1038 * pass NULL for @a props and @a target. 1039 * 1040 * This function allows @a props to be NULL, but the parameter is 1041 * otherwise described by svn_editor_add_file(). 1042 * 1043 * For all restrictions on driving the editor, see #svn_editor_t. 1044 * @since New in 1.8. 1045 */ 1046svn_error_t * 1047svn_editor_alter_symlink(svn_editor_t *editor, 1048 const char *relpath, 1049 svn_revnum_t revision, 1050 apr_hash_t *props, 1051 const char *target); 1052 1053/** Drive @a editor's #svn_editor_cb_delete_t callback. 1054 * 1055 * Delete the existing node at @a relpath, expected to be identical to 1056 * revision @a revision of that path. 1057 * 1058 * For all restrictions on driving the editor, see #svn_editor_t. 1059 * @since New in 1.8. 1060 */ 1061svn_error_t * 1062svn_editor_delete(svn_editor_t *editor, 1063 const char *relpath, 1064 svn_revnum_t revision); 1065 1066/** Drive @a editor's #svn_editor_cb_copy_t callback. 1067 * 1068 * Copy the node at @a src_relpath, expected to be identical to revision @a 1069 * src_revision of that path, to @a dst_relpath. 1070 * 1071 * For a description of @a replaces_rev, see svn_editor_add_file(). 1072 * 1073 * @note See the general instructions on paths for this API. Since the 1074 * @a src_relpath argument must generally be able to reference any node 1075 * in the repository, the implication is that the editor's root must be 1076 * the repository root. 1077 * 1078 * For all restrictions on driving the editor, see #svn_editor_t. 1079 * @since New in 1.8. 1080 */ 1081svn_error_t * 1082svn_editor_copy(svn_editor_t *editor, 1083 const char *src_relpath, 1084 svn_revnum_t src_revision, 1085 const char *dst_relpath, 1086 svn_revnum_t replaces_rev); 1087 1088/** Drive @a editor's #svn_editor_cb_move_t callback. 1089 * 1090 * Move the node at @a src_relpath to @a dst_relpath. 1091 * 1092 * @a src_revision specifies the revision at which the receiver should 1093 * expect to find this node. That is, @a src_relpath at the start of 1094 * the whole edit and @a src_relpath at @a src_revision must lie within 1095 * the same node-rev (aka history-segment). This is just like the 1096 * revisions specified to svn_editor_delete() and svn_editor_rotate(). 1097 * 1098 * For a description of @a replaces_rev, see svn_editor_add_file(). 1099 * 1100 * ### what happens if one side of this move is not "within" the receiver's 1101 * ### set of paths? 1102 * 1103 * For all restrictions on driving the editor, see #svn_editor_t. 1104 * @since New in 1.8. 1105 */ 1106svn_error_t * 1107svn_editor_move(svn_editor_t *editor, 1108 const char *src_relpath, 1109 svn_revnum_t src_revision, 1110 const char *dst_relpath, 1111 svn_revnum_t replaces_rev); 1112 1113/** Drive @a editor's #svn_editor_cb_rotate_t callback. 1114 * 1115 * Perform a rotation among multiple nodes in the target tree. 1116 * 1117 * The @a relpaths and @a revisions arrays (pair-wise) specify nodes in the 1118 * tree which are located at a path and expected to be at a specific 1119 * revision. These nodes are simultaneously moved in a rotation pattern. 1120 * For example, the node at index 0 of @a relpaths and @a revisions will 1121 * be moved to the relpath specified at index 1 of @a relpaths. The node 1122 * at index 1 will be moved to the location at index 2. The node at index 1123 * N-1 will be moved to the relpath specified at index 0. 1124 * 1125 * The simplest form of this operation is to swap nodes A and B. One may 1126 * think to move A to a temporary location T, then move B to A, then move 1127 * T to B. However, this last move violations the Once Rule by moving T 1128 * (which had already by edited by the move from A). In order to keep the 1129 * restrictions against multiple moves of a single node, the rotation 1130 * operation is needed for certain types of tree edits. 1131 * 1132 * ### what happens if one of the paths of the rotation is not "within" the 1133 * ### receiver's set of paths? 1134 * 1135 * For all restrictions on driving the editor, see #svn_editor_t. 1136 * @since New in 1.8. 1137 */ 1138svn_error_t * 1139svn_editor_rotate(svn_editor_t *editor, 1140 const apr_array_header_t *relpaths, 1141 const apr_array_header_t *revisions); 1142 1143/** Drive @a editor's #svn_editor_cb_complete_t callback. 1144 * 1145 * Send word that the edit has been completed successfully. 1146 * 1147 * For all restrictions on driving the editor, see #svn_editor_t. 1148 * @since New in 1.8. 1149 */ 1150svn_error_t * 1151svn_editor_complete(svn_editor_t *editor); 1152 1153/** Drive @a editor's #svn_editor_cb_abort_t callback. 1154 * 1155 * Notify that the edit transmission was not successful. 1156 * ### TODO @todo Shouldn't we add a reason-for-aborting argument? 1157 * 1158 * For all restrictions on driving the editor, see #svn_editor_t. 1159 * @since New in 1.8. 1160 */ 1161svn_error_t * 1162svn_editor_abort(svn_editor_t *editor); 1163 1164/** @} */ 1165 1166/** @} */ 1167 1168/** A temporary API which conditionally inserts a double editor shim 1169 * into the chain of delta editors. Used for testing Editor v2. 1170 * 1171 * Whether or not the shims are inserted is controlled by a compile-time 1172 * option in libsvn_delta/compat.c. 1173 * 1174 * @note The use of these shims and this API will likely cause all kinds 1175 * of performance degredation. (Which is actually a moot point since they 1176 * don't even work properly yet anyway.) 1177 */ 1178svn_error_t * 1179svn_editor__insert_shims(const svn_delta_editor_t **deditor_out, 1180 void **dedit_baton_out, 1181 const svn_delta_editor_t *deditor_in, 1182 void *dedit_baton_in, 1183 const char *repos_root, 1184 const char *base_dir, 1185 svn_delta_shim_callbacks_t *shim_callbacks, 1186 apr_pool_t *result_pool, 1187 apr_pool_t *scratch_pool); 1188 1189 1190#ifdef __cplusplus 1191} 1192#endif /* __cplusplus */ 1193 1194#endif /* SVN_EDITOR_H */ 1195