GME  13
Functions
Property functions
Client working copy management
Collaboration diagram for Property functions:

Functions

svn_error_tsvn_client_propset_remote (const char *propname, const svn_string_t *propval, const char *url, svn_boolean_t skip_checks, svn_revnum_t base_revision_for_url, const apr_hash_t *revprop_table, svn_commit_callback2_t commit_callback, void *commit_baton, svn_client_ctx_t *ctx, apr_pool_t *scratch_pool)
svn_error_tsvn_client_propset_local (const char *propname, const svn_string_t *propval, const apr_array_header_t *targets, svn_depth_t depth, svn_boolean_t skip_checks, const apr_array_header_t *changelists, svn_client_ctx_t *ctx, apr_pool_t *scratch_pool)
SVN_DEPRECATED svn_error_tsvn_client_propset3 (svn_commit_info_t **commit_info_p, const char *propname, const svn_string_t *propval, const char *target, svn_depth_t depth, svn_boolean_t skip_checks, svn_revnum_t base_revision_for_url, const apr_array_header_t *changelists, const apr_hash_t *revprop_table, svn_client_ctx_t *ctx, apr_pool_t *pool)
SVN_DEPRECATED svn_error_tsvn_client_propset2 (const char *propname, const svn_string_t *propval, const char *target, svn_boolean_t recurse, svn_boolean_t skip_checks, svn_client_ctx_t *ctx, apr_pool_t *pool)
SVN_DEPRECATED svn_error_tsvn_client_propset (const char *propname, const svn_string_t *propval, const char *target, svn_boolean_t recurse, apr_pool_t *pool)
svn_error_tsvn_client_revprop_set2 (const char *propname, const svn_string_t *propval, const svn_string_t *original_propval, const char *URL, const svn_opt_revision_t *revision, svn_revnum_t *set_rev, svn_boolean_t force, svn_client_ctx_t *ctx, apr_pool_t *pool)
SVN_DEPRECATED svn_error_tsvn_client_revprop_set (const char *propname, const svn_string_t *propval, const char *URL, const svn_opt_revision_t *revision, svn_revnum_t *set_rev, svn_boolean_t force, svn_client_ctx_t *ctx, apr_pool_t *pool)
svn_error_tsvn_client_propget5 (apr_hash_t **props, apr_array_header_t **inherited_props, const char *propname, const char *target, const svn_opt_revision_t *peg_revision, const svn_opt_revision_t *revision, svn_revnum_t *actual_revnum, svn_depth_t depth, const apr_array_header_t *changelists, svn_client_ctx_t *ctx, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
SVN_DEPRECATED svn_error_tsvn_client_propget4 (apr_hash_t **props, const char *propname, const char *target, const svn_opt_revision_t *peg_revision, const svn_opt_revision_t *revision, svn_revnum_t *actual_revnum, svn_depth_t depth, const apr_array_header_t *changelists, svn_client_ctx_t *ctx, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
SVN_DEPRECATED svn_error_tsvn_client_propget3 (apr_hash_t **props, const char *propname, const char *target, const svn_opt_revision_t *peg_revision, const svn_opt_revision_t *revision, svn_revnum_t *actual_revnum, svn_depth_t depth, const apr_array_header_t *changelists, svn_client_ctx_t *ctx, apr_pool_t *pool)
SVN_DEPRECATED svn_error_tsvn_client_propget2 (apr_hash_t **props, const char *propname, const char *target, const svn_opt_revision_t *peg_revision, const svn_opt_revision_t *revision, svn_boolean_t recurse, svn_client_ctx_t *ctx, apr_pool_t *pool)
SVN_DEPRECATED svn_error_tsvn_client_propget (apr_hash_t **props, const char *propname, const char *target, const svn_opt_revision_t *revision, svn_boolean_t recurse, svn_client_ctx_t *ctx, apr_pool_t *pool)
svn_error_tsvn_client_revprop_get (const char *propname, svn_string_t **propval, const char *URL, const svn_opt_revision_t *revision, svn_revnum_t *set_rev, svn_client_ctx_t *ctx, apr_pool_t *pool)
svn_error_tsvn_client_proplist4 (const char *target, const svn_opt_revision_t *peg_revision, const svn_opt_revision_t *revision, svn_depth_t depth, const apr_array_header_t *changelists, svn_boolean_t get_target_inherited_props, svn_proplist_receiver2_t receiver, void *receiver_baton, svn_client_ctx_t *ctx, apr_pool_t *scratch_pool)
SVN_DEPRECATED svn_error_tsvn_client_proplist3 (const char *target, const svn_opt_revision_t *peg_revision, const svn_opt_revision_t *revision, svn_depth_t depth, const apr_array_header_t *changelists, svn_proplist_receiver_t receiver, void *receiver_baton, svn_client_ctx_t *ctx, apr_pool_t *pool)
SVN_DEPRECATED svn_error_tsvn_client_proplist2 (apr_array_header_t **props, const char *target, const svn_opt_revision_t *peg_revision, const svn_opt_revision_t *revision, svn_boolean_t recurse, svn_client_ctx_t *ctx, apr_pool_t *pool)
SVN_DEPRECATED svn_error_tsvn_client_proplist (apr_array_header_t **props, const char *target, const svn_opt_revision_t *revision, svn_boolean_t recurse, svn_client_ctx_t *ctx, apr_pool_t *pool)
svn_error_tsvn_client_revprop_list (apr_hash_t **props, const char *URL, const svn_opt_revision_t *revision, svn_revnum_t *set_rev, svn_client_ctx_t *ctx, apr_pool_t *pool)

Detailed Description

Properties

Note that certain svn-controlled properties must always have their values set and stored in UTF8 with LF line endings. When retrieving these properties, callers must convert the values back to native locale and native line-endings before displaying them to the user. For help with this task, see svn_prop_needs_translation(), svn_subst_translate_string(), and svn_subst_detranslate_string().


Function Documentation

SVN_DEPRECATED svn_error_t* svn_client_propget ( apr_hash_t **  props,
const char *  propname,
const char *  target,
const svn_opt_revision_t revision,
svn_boolean_t  recurse,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Similar to svn_client_propget2(), except that peg_revision is always the same as revision.

Deprecated:
Provided for backward compatibility with the 1.1 API.
SVN_DEPRECATED svn_error_t* svn_client_propget2 ( apr_hash_t **  props,
const char *  propname,
const char *  target,
const svn_opt_revision_t peg_revision,
const svn_opt_revision_t revision,
svn_boolean_t  recurse,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Similar to svn_client_propget3(), except that actual_revnum and changelists are always NULL, and depth is set according to recurse: if recurse is TRUE, then depth is svn_depth_infinity, else svn_depth_empty.

Deprecated:
Provided for backward compatibility with the 1.4 API.
SVN_DEPRECATED svn_error_t* svn_client_propget3 ( apr_hash_t **  props,
const char *  propname,
const char *  target,
const svn_opt_revision_t peg_revision,
const svn_opt_revision_t revision,
svn_revnum_t actual_revnum,
svn_depth_t  depth,
const apr_array_header_t changelists,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Similar to svn_client_propget4(), but with the following change to the output hash keys: keys are `char *' paths, prefixed by target, which is a working copy path or a URL.

This function returns SVN_ERR_ENTRY_NOT_FOUND where svn_client_propget4 would return SVN_ERR_UNVERSIONED_RESOURCE.

Since:
New in 1.5.
Deprecated:
Provided for backward compatibility with the 1.6 API.
SVN_DEPRECATED svn_error_t* svn_client_propget4 ( apr_hash_t **  props,
const char *  propname,
const char *  target,
const svn_opt_revision_t peg_revision,
const svn_opt_revision_t revision,
svn_revnum_t actual_revnum,
svn_depth_t  depth,
const apr_array_header_t changelists,
svn_client_ctx_t ctx,
apr_pool_t result_pool,
apr_pool_t scratch_pool 
)

Similar to svn_client_propget5 but with inherited_props always passed as NULL.

Since:
New in 1.7.
Deprecated:
Provided for backward compatibility with the 1.7 API.
svn_error_t* svn_client_propget5 ( apr_hash_t **  props,
apr_array_header_t **  inherited_props,
const char *  propname,
const char *  target,
const svn_opt_revision_t peg_revision,
const svn_opt_revision_t revision,
svn_revnum_t actual_revnum,
svn_depth_t  depth,
const apr_array_header_t changelists,
svn_client_ctx_t ctx,
apr_pool_t result_pool,
apr_pool_t scratch_pool 
)

Set *props to a hash table whose keys are absolute paths or URLs of items on which property propname is explicitly set, and whose values are svn_string_t * representing the property value for propname at that path.

If inherited_props is not NULL, then set *inherited_props to a depth-first ordered array of svn_prop_inherited_item_t * structures representing the properties inherited by target. If target is a working copy path, then properties inherited by target as far as the root of the working copy are obtained from the working copy's actual property values. Properties inherited from above the working copy root come from the inherited properties cache. If target is a URL, then the inherited properties come from the repository. If inherited_props is not NULL and no inheritable properties are found, then set *inherited_props to an empty array.

The svn_prop_inherited_item_t->path_or_url members of the svn_prop_inherited_item_t * structures in *inherited_props are URLs if target is a URL or if target is a working copy path but the property represented by the structure is above the working copy root (i.e. the inherited property is from the cache). In all other cases the svn_prop_inherited_item_t->path_or_url members are absolute working copy paths.

Allocate *props (including keys and values) and *inherited_props (including its elements) in result_pool, use scratch_pool for temporary allocations.

target is a WC absolute path or a URL.

Don't store any path, not even target, if it does not have a property named propname.

If revision->kind is svn_opt_revision_unspecified, then: get properties from the working copy if target is a working copy path, or from the repository head if target is a URL. Else get the properties as of revision. The actual node revision selected is determined by the path as it exists in peg_revision. If peg_revision->kind is svn_opt_revision_unspecified, then it defaults to svn_opt_revision_head for URLs or svn_opt_revision_working for WC targets. Use the authentication baton in ctx for authentication if contacting the repository. If actual_revnum is not NULL, the actual revision number used for the fetch is stored in *actual_revnum.

If depth is svn_depth_empty, fetch the property from target only; if svn_depth_files, fetch from target and its file children (if any); if svn_depth_immediates, from target and all of its immediate children (both files and directories); if svn_depth_infinity, from target and everything beneath it.

changelists is an array of const char * changelist names, used as a restrictive filter on items whose properties are gotten; that is, don't get propname on any item unless it's a member of one of those changelists. If changelists is empty (or altogether NULL), no changelist filtering occurs.

If error, don't touch *props, otherwise *props is a hash table even if empty.

This function returns SVN_ERR_UNVERSIONED_RESOURCE when it is called on unversioned nodes.

Since:
New in 1.8.
SVN_DEPRECATED svn_error_t* svn_client_proplist ( apr_array_header_t **  props,
const char *  target,
const svn_opt_revision_t revision,
svn_boolean_t  recurse,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Similar to svn_client_proplist2(), except that peg_revision is always the same as revision.

Deprecated:
Provided for backward compatibility with the 1.1 API.
SVN_DEPRECATED svn_error_t* svn_client_proplist2 ( apr_array_header_t **  props,
const char *  target,
const svn_opt_revision_t peg_revision,
const svn_opt_revision_t revision,
svn_boolean_t  recurse,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Similar to svn_client_proplist3(), except the properties are returned as an array of svn_client_proplist_item_t * structures instead of by invoking the receiver function, there's no support for changelists filtering, and recurse is used instead of a svn_depth_t parameter (FALSE corresponds to svn_depth_empty, and TRUE to svn_depth_infinity).

Since:
New in 1.2.
Deprecated:
Provided for backward compatibility with the 1.4 API.
SVN_DEPRECATED svn_error_t* svn_client_proplist3 ( const char *  target,
const svn_opt_revision_t peg_revision,
const svn_opt_revision_t revision,
svn_depth_t  depth,
const apr_array_header_t changelists,
svn_proplist_receiver_t  receiver,
void *  receiver_baton,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Similar to svn_client_proplist4(), except that the receiver type is a svn_proplist_receiver_t, get_target_inherited_props is always passed NULL, and there is no separate scratch pool.

Since:
New in 1.5.
Deprecated:
Provided for backward compatibility with the 1.7 API.
svn_error_t* svn_client_proplist4 ( const char *  target,
const svn_opt_revision_t peg_revision,
const svn_opt_revision_t revision,
svn_depth_t  depth,
const apr_array_header_t changelists,
svn_boolean_t  get_target_inherited_props,
svn_proplist_receiver2_t  receiver,
void *  receiver_baton,
svn_client_ctx_t ctx,
apr_pool_t scratch_pool 
)

Invoke receiver with receiver_baton to return the regular explicit, and possibly the inherited, properties of target, a URL or working copy path. receiver will be called for each path encountered.

target is a WC path or a URL.

If revision->kind is svn_opt_revision_unspecified, then get the explicit (and possibly the inherited) properties from the working copy, if target is a working copy path, or from the repository head if target is a URL. Else get the properties as of revision. The actual node revision selected is determined by the path as it exists in peg_revision. If peg_revision->kind is svn_opt_revision_unspecified, then it defaults to svn_opt_revision_head for URLs or svn_opt_revision_working for WC targets. Use the authentication baton cached in ctx for authentication if contacting the repository.

If depth is svn_depth_empty, list only the properties of target itself. If depth is svn_depth_files, and target is a directory, list the properties of target and its file entries. If svn_depth_immediates, list the properties of its immediate file and directory entries. If svn_depth_infinity, list the properties of its file entries and recurse (with svn_depth_infinity) on directory entries. svn_depth_unknown is equivalent to svn_depth_empty. All other values produce undefined results.

changelists is an array of const char * changelist names, used as a restrictive filter on items whose properties are listed; that is, don't list properties on any item unless it's a member of one of those changelists. If changelists is empty (or altogether NULL), no changelist filtering occurs.

If get_target_inherited_props is true, then also return any inherited properties when receiver is called for target. If target is a working copy path, then properties inherited by target as far as the root of the working copy are obtained from the working copy's actual property values. Properties inherited from above the working copy root come from the inherited properties cache. If target is a URL, then the inherited properties come from the repository. If get_target_inherited_props is false, then no inherited properties are returned to receiver.

If target is not found, return the error SVN_ERR_ENTRY_NOT_FOUND.

Since:
New in 1.8.
SVN_DEPRECATED svn_error_t* svn_client_propset ( const char *  propname,
const svn_string_t propval,
const char *  target,
svn_boolean_t  recurse,
apr_pool_t pool 
)

Like svn_client_propset2(), but with skip_checks always FALSE and a newly created ctx.

Deprecated:
Provided for backward compatibility with the 1.1 API.
SVN_DEPRECATED svn_error_t* svn_client_propset2 ( const char *  propname,
const svn_string_t propval,
const char *  target,
svn_boolean_t  recurse,
svn_boolean_t  skip_checks,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Like svn_client_propset3(), but with base_revision_for_url always SVN_INVALID_REVNUM; commit_info_p always NULL; changelists always NULL; revprop_table always NULL; and depth set according to recurse: if recurse is TRUE, depth is svn_depth_infinity, else svn_depth_empty.

Deprecated:
Provided for backward compatibility with the 1.4 API.
SVN_DEPRECATED svn_error_t* svn_client_propset3 ( svn_commit_info_t **  commit_info_p,
const char *  propname,
const svn_string_t propval,
const char *  target,
svn_depth_t  depth,
svn_boolean_t  skip_checks,
svn_revnum_t  base_revision_for_url,
const apr_array_header_t changelists,
const apr_hash_t revprop_table,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

An amalgamation of svn_client_propset_local() and svn_client_propset_remote() that takes only a single target, and returns the commit info in *commit_info_p rather than through a callback function.

Since:
New in 1.5.
Deprecated:
Provided for backward compatibility with the 1.6 API.
svn_error_t* svn_client_propset_local ( const char *  propname,
const svn_string_t propval,
const apr_array_header_t targets,
svn_depth_t  depth,
svn_boolean_t  skip_checks,
const apr_array_header_t changelists,
svn_client_ctx_t ctx,
apr_pool_t scratch_pool 
)

Set propname to propval on each (const char *) target in targets. The targets must be all working copy paths. A propval of NULL will delete the property.

If depth is svn_depth_empty, set the property on each member of targets only; if svn_depth_files, set it on targets and their file children (if any); if svn_depth_immediates, on targets and all of their immediate children (both files and directories); if svn_depth_infinity, on targets and everything beneath them.

changelists is an array of const char * changelist names, used as a restrictive filter on items whose properties are set; that is, don't set properties on any item unless it's a member of one of those changelists. If changelists is empty (or altogether NULL), no changelist filtering occurs.

If propname is an svn-controlled property (i.e. prefixed with SVN_PROP_PREFIX), then the caller is responsible for ensuring that the value is UTF8-encoded and uses LF line-endings.

If skip_checks is TRUE, do no validity checking. But if skip_checks is FALSE, and propname is not a valid property for targets, return an error, either SVN_ERR_ILLEGAL_TARGET (if the property is not appropriate for targets), or SVN_ERR_BAD_MIME_TYPE (if propname is "svn:mime-type", but propval is not a valid mime-type).

If ctx->cancel_func is non-NULL, invoke it passing ctx->cancel_baton at various places during the operation.

Use scratch_pool for all memory allocation.

Since:
New in 1.7.
svn_error_t* svn_client_propset_remote ( const char *  propname,
const svn_string_t propval,
const char *  url,
svn_boolean_t  skip_checks,
svn_revnum_t  base_revision_for_url,
const apr_hash_t revprop_table,
svn_commit_callback2_t  commit_callback,
void *  commit_baton,
svn_client_ctx_t ctx,
apr_pool_t scratch_pool 
)

Set propname to propval on url. A propval of NULL will delete the property.

Immediately attempt to commit the property change in the repository, using the authentication baton in ctx and ctx->log_msg_func3/ctx->log_msg_baton3.

If the property has changed on url since revision base_revision_for_url (which must not be SVN_INVALID_REVNUM), no change will be made and an error will be returned.

If non-NULL, revprop_table is a hash table holding additional, custom revision properties (const char * names mapped to svn_string_t * values) to be set on the new revision. This table cannot contain any standard Subversion properties.

If commit_callback is non-NULL, then call commit_callback with commit_baton and a svn_commit_info_t for the commit.

If propname is an svn-controlled property (i.e. prefixed with SVN_PROP_PREFIX), then the caller is responsible for ensuring that the value is UTF8-encoded and uses LF line-endings.

If skip_checks is TRUE, do no validity checking. But if skip_checks is FALSE, and propname is not a valid property for url, return an error, either SVN_ERR_ILLEGAL_TARGET (if the property is not appropriate for url), or * SVN_ERR_BAD_MIME_TYPE (if propname is "svn:mime-type", but propval is not a valid mime-type).

Use scratch_pool for all memory allocation.

Since:
New in 1.7.
svn_error_t* svn_client_revprop_get ( const char *  propname,
svn_string_t **  propval,
const char *  URL,
const svn_opt_revision_t revision,
svn_revnum_t set_rev,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Set *propval to the value of propname on revision revision in the repository represented by URL. Use the authentication baton in ctx for authentication, and pool for all memory allocation. Return the actual rev queried in *set_rev.

Note that unlike its cousin svn_client_propget(), this routine doesn't affect the working copy at all; it's a pure network operation that queries an *unversioned* property attached to a revision. This can query log messages, dates, authors, and the like.

svn_error_t* svn_client_revprop_list ( apr_hash_t **  props,
const char *  URL,
const svn_opt_revision_t revision,
svn_revnum_t set_rev,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Set *props to a hash of the revision props attached to revision in the repository represented by URL. Use the authentication baton cached in ctx for authentication, and pool for all memory allocation. Return the actual rev queried in *set_rev.

The allocated hash maps (const char *) property names to (svn_string_t *) property values.

Note that unlike its cousin svn_client_proplist(), this routine doesn't read a working copy at all; it's a pure network operation that reads *unversioned* properties attached to a revision.

SVN_DEPRECATED svn_error_t* svn_client_revprop_set ( const char *  propname,
const svn_string_t propval,
const char *  URL,
const svn_opt_revision_t revision,
svn_revnum_t set_rev,
svn_boolean_t  force,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Similar to svn_client_revprop_set2(), but with original_propval always NULL.

Deprecated:
Provided for backward compatibility with the 1.5 API.
svn_error_t* svn_client_revprop_set2 ( const char *  propname,
const svn_string_t propval,
const svn_string_t original_propval,
const char *  URL,
const svn_opt_revision_t revision,
svn_revnum_t set_rev,
svn_boolean_t  force,
svn_client_ctx_t ctx,
apr_pool_t pool 
)

Set propname to propval on revision revision in the repository represented by URL. Use the authentication baton in ctx for authentication, and pool for all memory allocation. Return the actual rev affected in *set_rev. A propval of NULL will delete the property.

If original_propval is non-NULL, then just before setting the new value, check that the old value matches original_propval; if they do not match, return the error SVN_ERR_RA_OUT_OF_DATE. This is to help clients support interactive editing of revprops: without this check, the window during which the property may change underneath the user is as wide as the amount of time the user spends editing the property. With this check, the window is reduced to a small, constant amount of time right before we set the new value. (To check that an old value is still non-existent, set original_propval->data to NULL, and original_propval->len is ignored.) If the server advertises SVN_RA_CAPABILITY_ATOMIC_REVPROPS, the check of original_propval is done atomically.

Note: the representation of "property is not set" in original_propval differs from the representation in other APIs (such as svn_fs_change_rev_prop2() and svn_ra_change_rev_prop2()).

If force is TRUE, allow newlines in the author property.

If propname is an svn-controlled property (i.e. prefixed with SVN_PROP_PREFIX), then the caller is responsible for ensuring that the value UTF8-encoded and uses LF line-endings.

Note that unlike its cousin svn_client_propset3(), this routine doesn't affect the working copy at all; it's a pure network operation that changes an *unversioned* property attached to a revision. This can be used to tweak log messages, dates, authors, and the like. Be careful: it's a lossy operation.

ctx->notify_func2 and ctx->notify_baton2 are the notification functions and baton which are called upon successful setting of the property.

Also note that unless the administrator creates a pre-revprop-change hook in the repository, this feature will fail.

Since:
New in 1.6.