Subversion
Data Structures | Typedefs | Enumerations | Functions
Notification callback handling

In many cases, the WC library will scan a working copy and make changes. The caller usually wants to know when each of these changes has been made, so that it can display some kind of notification to the user. More...

Data Structures

struct  svn_wc_notify_t
 Structure used in the svn_wc_notify_func2_t function. More...
 

Typedefs

typedef enum svn_wc_notify_action_t svn_wc_notify_action_t
 The type of action occurring.
 
typedef enum svn_wc_notify_state_t svn_wc_notify_state_t
 The type of notification that is occurring.
 
typedef enum svn_wc_notify_lock_state_t svn_wc_notify_lock_state_t
 What happened to a lock during an operation. More...
 
typedef struct svn_wc_notify_t svn_wc_notify_t
 Structure used in the svn_wc_notify_func2_t function. More...
 
typedef void(* svn_wc_notify_func2_t) (void *baton, const svn_wc_notify_t *notify, apr_pool_t *pool)
 Notify the world that notify->action has happened to notify->path. More...
 
typedef void(* svn_wc_notify_func_t) (void *baton, const char *path, svn_wc_notify_action_t action, svn_node_kind_t kind, const char *mime_type, svn_wc_notify_state_t content_state, svn_wc_notify_state_t prop_state, svn_revnum_t revision)
 Similar to svn_wc_notify_func2_t, but takes the information as arguments instead of struct fields. More...
 

Enumerations

enum  svn_wc_notify_action_t {
  svn_wc_notify_add = 0,
  svn_wc_notify_copy,
  svn_wc_notify_delete,
  svn_wc_notify_restore,
  svn_wc_notify_revert,
  svn_wc_notify_failed_revert,
  svn_wc_notify_resolved,
  svn_wc_notify_skip,
  svn_wc_notify_update_delete,
  svn_wc_notify_update_add,
  svn_wc_notify_update_update,
  svn_wc_notify_update_completed,
  svn_wc_notify_update_external,
  svn_wc_notify_status_completed,
  svn_wc_notify_status_external,
  svn_wc_notify_commit_modified,
  svn_wc_notify_commit_added,
  svn_wc_notify_commit_deleted,
  svn_wc_notify_commit_replaced,
  svn_wc_notify_commit_postfix_txdelta,
  svn_wc_notify_blame_revision,
  svn_wc_notify_locked,
  svn_wc_notify_unlocked,
  svn_wc_notify_failed_lock,
  svn_wc_notify_failed_unlock,
  svn_wc_notify_exists,
  svn_wc_notify_changelist_set,
  svn_wc_notify_changelist_clear,
  svn_wc_notify_changelist_moved,
  svn_wc_notify_merge_begin,
  svn_wc_notify_foreign_merge_begin,
  svn_wc_notify_update_replace,
  svn_wc_notify_property_added,
  svn_wc_notify_property_modified,
  svn_wc_notify_property_deleted,
  svn_wc_notify_property_deleted_nonexistent,
  svn_wc_notify_revprop_set,
  svn_wc_notify_revprop_deleted,
  svn_wc_notify_merge_completed,
  svn_wc_notify_tree_conflict,
  svn_wc_notify_failed_external,
  svn_wc_notify_update_started,
  svn_wc_notify_update_skip_obstruction,
  svn_wc_notify_update_skip_working_only,
  svn_wc_notify_update_skip_access_denied,
  svn_wc_notify_update_external_removed,
  svn_wc_notify_update_shadowed_add,
  svn_wc_notify_update_shadowed_update,
  svn_wc_notify_update_shadowed_delete,
  svn_wc_notify_merge_record_info,
  svn_wc_notify_upgraded_path,
  svn_wc_notify_merge_record_info_begin,
  svn_wc_notify_merge_elide_info,
  svn_wc_notify_patch,
  svn_wc_notify_patch_applied_hunk,
  svn_wc_notify_patch_rejected_hunk,
  svn_wc_notify_patch_hunk_already_applied,
  svn_wc_notify_commit_copied,
  svn_wc_notify_commit_copied_replaced,
  svn_wc_notify_url_redirect,
  svn_wc_notify_path_nonexistent,
  svn_wc_notify_exclude,
  svn_wc_notify_failed_conflict,
  svn_wc_notify_failed_missing,
  svn_wc_notify_failed_out_of_date,
  svn_wc_notify_failed_no_parent,
  svn_wc_notify_failed_locked,
  svn_wc_notify_failed_forbidden_by_server,
  svn_wc_notify_skip_conflicted,
  svn_wc_notify_update_broken_lock,
  svn_wc_notify_failed_obstruction,
  svn_wc_notify_conflict_resolver_starting,
  svn_wc_notify_conflict_resolver_done,
  svn_wc_notify_left_local_modifications,
  svn_wc_notify_foreign_copy_begin,
  svn_wc_notify_move_broken,
  svn_wc_notify_cleanup_external,
  svn_wc_notify_failed_requires_target,
  svn_wc_notify_info_external,
  svn_wc_notify_commit_finalizing,
  svn_wc_notify_resolved_text,
  svn_wc_notify_resolved_prop,
  svn_wc_notify_resolved_tree,
  svn_wc_notify_begin_search_tree_conflict_details,
  svn_wc_notify_tree_conflict_details_progress,
  svn_wc_notify_end_search_tree_conflict_details
}
 The type of action occurring. More...
 
enum  svn_wc_notify_state_t {
  svn_wc_notify_state_inapplicable = 0,
  svn_wc_notify_state_unknown,
  svn_wc_notify_state_unchanged,
  svn_wc_notify_state_missing,
  svn_wc_notify_state_obstructed,
  svn_wc_notify_state_changed,
  svn_wc_notify_state_merged,
  svn_wc_notify_state_conflicted,
  svn_wc_notify_state_source_missing
}
 The type of notification that is occurring. More...
 
enum  svn_wc_notify_lock_state_t {
  svn_wc_notify_lock_state_inapplicable = 0,
  svn_wc_notify_lock_state_unknown,
  svn_wc_notify_lock_state_unchanged,
  svn_wc_notify_lock_state_locked,
  svn_wc_notify_lock_state_unlocked
}
 What happened to a lock during an operation. More...
 

Functions

svn_wc_notify_tsvn_wc_create_notify (const char *path, svn_wc_notify_action_t action, apr_pool_t *pool)
 Allocate an svn_wc_notify_t structure in pool, initialize and return it. More...
 
svn_wc_notify_tsvn_wc_create_notify_url (const char *url, svn_wc_notify_action_t action, apr_pool_t *pool)
 Allocate an svn_wc_notify_t structure in pool, initialize and return it. More...
 
svn_wc_notify_tsvn_wc_dup_notify (const svn_wc_notify_t *notify, apr_pool_t *pool)
 Return a deep copy of notify, allocated in pool. More...
 

Detailed Description

In many cases, the WC library will scan a working copy and make changes. The caller usually wants to know when each of these changes has been made, so that it can display some kind of notification to the user.

These notifications have a standard callback function type, which takes the path of the file that was affected, and a caller- supplied baton.

Note
The callback is a 'void' return – this is a simple reporting mechanism, rather than an opportunity for the caller to alter the operation of the WC library.
Some of the actions are used across several different Subversion commands. For example, the update actions are also used for checkouts, switches, and merges.

Typedef Documentation

◆ svn_wc_notify_func2_t

typedef void(* svn_wc_notify_func2_t) (void *baton, const svn_wc_notify_t *notify, apr_pool_t *pool)

Notify the world that notify->action has happened to notify->path.

Recommendation: callers of svn_wc_notify_func2_t should avoid invoking it multiple times on the same path within a given operation, and implementations should not bother checking for such duplicate calls. For example, in an update, the caller should not invoke the notify func on receiving a prop change and then again on receiving a text change. Instead, wait until all changes have been received, and then invoke the notify func once (from within an svn_delta_editor_t's close_file(), for example), passing the appropriate notify->content_state and notify->prop_state flags.

Since
New in 1.2.

Definition at line 1553 of file svn_wc.h.

◆ svn_wc_notify_func_t

typedef void(* svn_wc_notify_func_t) (void *baton, const char *path, svn_wc_notify_action_t action, svn_node_kind_t kind, const char *mime_type, svn_wc_notify_state_t content_state, svn_wc_notify_state_t prop_state, svn_revnum_t revision)

Similar to svn_wc_notify_func2_t, but takes the information as arguments instead of struct fields.

Deprecated:
Provided for backward compatibility with the 1.1 API.

Definition at line 1563 of file svn_wc.h.

◆ svn_wc_notify_lock_state_t

What happened to a lock during an operation.

Since
New in 1.2.

◆ svn_wc_notify_t

Structure used in the svn_wc_notify_func2_t function.

kind, content_state, prop_state and lock_state are from after action, not before.

Note
If action is svn_wc_notify_update_completed, then path has already been installed, so it is legitimate for an implementation of svn_wc_notify_func2_t to examine path in the working copy.
The purpose of the kind, mime_type, content_state, and prop_state fields is to provide "for free" information that an implementation is likely to want, and which it would otherwise be forced to deduce via expensive operations such as reading entries and properties. However, if the caller does not have this information, it will simply pass the corresponding ‘*_unknown’ values, and it is up to the implementation how to handle that (i.e., whether to attempt deduction, or just to punt and give a less informative notification).
Callers of notification functions should use svn_wc_create_notify() or svn_wc_create_notify_url() to create structures of this type to allow for extensibility.
Since
New in 1.2.

Enumeration Type Documentation

◆ svn_wc_notify_action_t

The type of action occurring.

Enumerator
svn_wc_notify_add 

Adding a path to revision control.

svn_wc_notify_copy 

Copying a versioned path.

svn_wc_notify_delete 

Deleting a versioned path.

svn_wc_notify_restore 

Restoring a missing path from the pristine text-base.

svn_wc_notify_revert 

Reverting a modified path.

svn_wc_notify_failed_revert 

A revert operation has failed.

svn_wc_notify_resolved 

All conflicts on a path were marked as resolved.

Note
As of 1.10, separate notifications are sent for individually resolved text, property, and tree conflicts. This notification is used only if all conflicts on a path were marked resolved at once.
svn_wc_notify_skip 

Skipping a path.

svn_wc_notify_update_delete 

Got a delete in an update.

svn_wc_notify_update_add 

Got an add in an update.

svn_wc_notify_update_update 

Got any other action in an update.

svn_wc_notify_update_completed 

The last notification in an update (including updates of externals).

svn_wc_notify_update_external 

Updating an external module.

svn_wc_notify_status_completed 

The last notification in a status (including status on externals).

svn_wc_notify_status_external 

Running status on an external module.

svn_wc_notify_commit_modified 

Committing a modification.

svn_wc_notify_commit_added 

Committing an addition.

svn_wc_notify_commit_deleted 

Committing a deletion.

svn_wc_notify_commit_replaced 

Committing a replacement.

svn_wc_notify_commit_postfix_txdelta 

Transmitting post-fix text-delta data for a file.

svn_wc_notify_blame_revision 

Processed a single revision's blame.

svn_wc_notify_locked 

Locking a path.

Since
New in 1.2.
svn_wc_notify_unlocked 

Unlocking a path.

Since
New in 1.2.
svn_wc_notify_failed_lock 

Failed to lock a path.

Since
New in 1.2.
svn_wc_notify_failed_unlock 

Failed to unlock a path.

Since
New in 1.2.
svn_wc_notify_exists 

Tried adding a path that already exists.

Since
New in 1.5.
svn_wc_notify_changelist_set 

Changelist name set.

Since
New in 1.5.
svn_wc_notify_changelist_clear 

Changelist name cleared.

Since
New in 1.5.
svn_wc_notify_changelist_moved 

Warn user that a path has moved from one changelist to another.

Since
New in 1.5.
Deprecated:
As of 1.7, separate clear and set notifications are sent.
svn_wc_notify_merge_begin 

A merge operation (to path) has begun.

See svn_wc_notify_t.merge_range.

Since
New in 1.5.
svn_wc_notify_foreign_merge_begin 

A merge operation (to path) from a foreign repository has begun.

See svn_wc_notify_t.merge_range.

Since
New in 1.5.
svn_wc_notify_update_replace 

Replace notification.

Since
New in 1.5.
svn_wc_notify_property_added 

Property added.

Since
New in 1.6.
svn_wc_notify_property_modified 

Property updated.

Since
New in 1.6.
svn_wc_notify_property_deleted 

Property deleted.

Since
New in 1.6.
svn_wc_notify_property_deleted_nonexistent 

Nonexistent property deleted.

Since
New in 1.6.
svn_wc_notify_revprop_set 

Revprop set.

Since
New in 1.6.
svn_wc_notify_revprop_deleted 

Revprop deleted.

Since
New in 1.6.
svn_wc_notify_merge_completed 

The last notification in a merge.

Since
New in 1.6.
svn_wc_notify_tree_conflict 

The path is a tree-conflict victim of the intended action (not a persistent tree-conflict from an earlier operation, but this operation caused the tree-conflict).

Since
New in 1.6.
svn_wc_notify_failed_external 

The path is a subdirectory referenced in an externals definition which is unable to be operated on.

Since
New in 1.6.
svn_wc_notify_update_started 

Starting an update operation.

Since
New in 1.7.
svn_wc_notify_update_skip_obstruction 

An update tried to add a file or directory at a path where a separate working copy was found.

Since
New in 1.7.
svn_wc_notify_update_skip_working_only 

An explicit update tried to update a file or directory that doesn't live in the repository and can't be brought in.

Since
New in 1.7.
svn_wc_notify_update_skip_access_denied 

An update tried to update a file or directory to which access could not be obtained.

Since
New in 1.7.
svn_wc_notify_update_external_removed 

An update operation removed an external working copy.

Since
New in 1.7.
svn_wc_notify_update_shadowed_add 

A node below an existing node was added during update.

Since
New in 1.7.
svn_wc_notify_update_shadowed_update 

A node below an existing node was updated during update.

Since
New in 1.7.
svn_wc_notify_update_shadowed_delete 

A node below an existing node was deleted during update.

Since
New in 1.7.
svn_wc_notify_merge_record_info 

The mergeinfo on path was updated.

Since
New in 1.7.
svn_wc_notify_upgraded_path 

A working copy directory was upgraded to the latest format.

Since
New in 1.7.
svn_wc_notify_merge_record_info_begin 

Mergeinfo describing a merge was recorded.

Since
New in 1.7.
svn_wc_notify_merge_elide_info 

Mergeinfo was removed due to elision.

Since
New in 1.7.
svn_wc_notify_patch 

A file in the working copy was patched.

Since
New in 1.7.
svn_wc_notify_patch_applied_hunk 

A hunk from a patch was applied.

Since
New in 1.7.
svn_wc_notify_patch_rejected_hunk 

A hunk from a patch was rejected.

Since
New in 1.7.
svn_wc_notify_patch_hunk_already_applied 

A hunk from a patch was found to already be applied.

Since
New in 1.7.
svn_wc_notify_commit_copied 

Committing a non-overwriting copy (path is the target of the copy, not the source).

Since
New in 1.7.
svn_wc_notify_commit_copied_replaced 

Committing an overwriting (replace) copy (path is the target of the copy, not the source).

Since
New in 1.7.
svn_wc_notify_url_redirect 

The server has instructed the client to follow a URL redirection.

Since
New in 1.7.
svn_wc_notify_path_nonexistent 

The operation was attempted on a path which doesn't exist.

Since
New in 1.7.
svn_wc_notify_exclude 

Removing a path by excluding it.

Since
New in 1.7.
svn_wc_notify_failed_conflict 

Operation failed because the node remains in conflict.

Since
New in 1.7.
svn_wc_notify_failed_missing 

Operation failed because an added node is missing.

Since
New in 1.7.
svn_wc_notify_failed_out_of_date 

Operation failed because a node is out of date.

Since
New in 1.7.
svn_wc_notify_failed_no_parent 

Operation failed because an added parent is not selected.

Since
New in 1.7.
svn_wc_notify_failed_locked 

Operation failed because a node is locked by another user and/or working copy.

Since
New in 1.7.
svn_wc_notify_failed_forbidden_by_server 

Operation failed because the operation was forbidden by the server.

Since
New in 1.7.
svn_wc_notify_skip_conflicted 

The operation skipped the path because it was conflicted.

Since
New in 1.7.
svn_wc_notify_update_broken_lock 

Just the lock on a file was removed during update.

Since
New in 1.8.
svn_wc_notify_failed_obstruction 

Operation failed because a node is obstructed.

Since
New in 1.8.
svn_wc_notify_conflict_resolver_starting 

Conflict resolver is starting.

This can be used by clients to detect when to display conflict summary information, for example.

Since
New in 1.8.
svn_wc_notify_conflict_resolver_done 

Conflict resolver is done.

This can be used by clients to detect when to display conflict summary information, for example.

Since
New in 1.8.
svn_wc_notify_left_local_modifications 

The current operation left local changes of something that was deleted The changes are available on (and below) the notified path.

Since
New in 1.8.
svn_wc_notify_foreign_copy_begin 

A copy from a foreign repository has started.

Since
New in 1.8.
svn_wc_notify_move_broken 

A move in the working copy has been broken, i.e.

degraded into a copy + delete. The notified path is the move source (the deleted path).

TODO: Provide path to move destination as well?

Since
New in 1.8.
svn_wc_notify_cleanup_external 

Running cleanup on an external module.

Since
New in 1.9.
svn_wc_notify_failed_requires_target 

The operation failed because the operation (E.g.

commit) is only valid if the operation includes this path.

Since
New in 1.9.
svn_wc_notify_info_external 

Running info on an external module.

Since
New in 1.9.
svn_wc_notify_commit_finalizing 

Finalizing commit.

Since
New in 1.9.
svn_wc_notify_resolved_text 

All text conflicts in a file were marked as resolved.

Since
New in 1.10.
svn_wc_notify_resolved_prop 

A property conflict on a path was marked as resolved.

The name of the property is specified in svn_wc_notify_t.prop_name.

Since
New in 1.10.
svn_wc_notify_resolved_tree 

A tree conflict on a path was marked as resolved.

Since
New in 1.10.
svn_wc_notify_begin_search_tree_conflict_details 

Starting to search the repository for details about a tree conflict.

Since
New in 1.10.
svn_wc_notify_tree_conflict_details_progress 

Progressing in search of repository for details about a tree conflict.

The revision being searched is specified in svn_wc_notify_t.revision.

Since
New in 1.10.
svn_wc_notify_end_search_tree_conflict_details 

Done searching the repository for details about a conflict.

Since
New in 1.10.

Definition at line 981 of file svn_wc.h.

◆ svn_wc_notify_lock_state_t

What happened to a lock during an operation.

Since
New in 1.2.
Enumerator
svn_wc_notify_lock_state_unchanged 

The lock wasn't changed.

svn_wc_notify_lock_state_locked 

The item was locked.

svn_wc_notify_lock_state_unlocked 

The item was unlocked.

Definition at line 1347 of file svn_wc.h.

◆ svn_wc_notify_state_t

The type of notification that is occurring.

Enumerator
svn_wc_notify_state_unknown 

Notifier doesn't know or isn't saying.

svn_wc_notify_state_unchanged 

The state did not change.

svn_wc_notify_state_missing 

The item wasn't present.

svn_wc_notify_state_obstructed 

An unversioned item obstructed work.

svn_wc_notify_state_changed 

Pristine state was modified.

svn_wc_notify_state_merged 

Modified state had mods merged in.

svn_wc_notify_state_conflicted 

Modified state got conflicting mods.

svn_wc_notify_state_source_missing 

The source to copy the file from is missing.

Definition at line 1312 of file svn_wc.h.

Function Documentation

◆ svn_wc_create_notify()

svn_wc_notify_t* svn_wc_create_notify ( const char *  path,
svn_wc_notify_action_t  action,
apr_pool_t *  pool 
)

Allocate an svn_wc_notify_t structure in pool, initialize and return it.

Set the path field of the created struct to path, and action to action. Set all other fields to their _unknown, NULL or invalid value, respectively. Make only a shallow copy of the pointer path.

Since
New in 1.2.

◆ svn_wc_create_notify_url()

svn_wc_notify_t* svn_wc_create_notify_url ( const char *  url,
svn_wc_notify_action_t  action,
apr_pool_t *  pool 
)

Allocate an svn_wc_notify_t structure in pool, initialize and return it.

Set the url field of the created struct to url, path to "." and action to action. Set all other fields to their _unknown, NULL or invalid value, respectively. Make only a shallow copy of the pointer url.

Since
New in 1.6.

◆ svn_wc_dup_notify()

svn_wc_notify_t* svn_wc_dup_notify ( const svn_wc_notify_t notify,
apr_pool_t *  pool 
)

Return a deep copy of notify, allocated in pool.

Since
New in 1.2.