# Externals
[Working copy management]

## Data Structures
struct | svn_wc_external_item2_t
| One external item. More...
struct | svn_wc_external_item_t
| One external item. More...
## Typedefs
typedef svn_error_t *(* | svn_wc_external_update_t )(void *baton, const char *local_abspath, const svn_string_t *old_val, const svn_string_t *new_val, svn_depth_t depth, apr_pool_t *scratch_pool)
| Callback for external definitions updates.
typedef struct svn_wc_traversal_info_t | svn_wc_traversal_info_t
| Traversal information is information gathered by a working copy crawl or update.
typedef struct svn_wc_external_item2_t | svn_wc_external_item2_t
| One external item.
typedef struct svn_wc_external_item_t | svn_wc_external_item_t
| One external item.
## Functions
svn_wc_traversal_info_t * | svn_wc_init_traversal_info (apr_pool_t *pool)
| Return a new, empty traversal info object, allocated in pool.
void | svn_wc_edited_externals (apr_hash_t **externals_old, apr_hash_t **externals_new, svn_wc_traversal_info_t *traversal_info)
| Set *externals_old and *externals_new to hash tables representing changes to values of the svn:externals property on directories traversed by traversal_info.
void | svn_wc_traversed_depths (apr_hash_t **depths, svn_wc_traversal_info_t *traversal_info)
| Set *depths to a hash table mapping `const char *` directory names (directories traversed by traversal_info) to `const char *` values (the depths of those directories, as converted by svn_depth_to_word()).
svn_error_t * | svn_wc_external_item_create (const svn_wc_external_item2_t **item, apr_pool_t *pool)
| Initialize an external item.
svn_wc_external_item2_t * | svn_wc_external_item2_dup (const svn_wc_external_item2_t *item, apr_pool_t *pool)
| Return a duplicate of item, allocated in pool.
svn_wc_external_item_t * | svn_wc_external_item_dup (const svn_wc_external_item_t *item, apr_pool_t *pool)
| Return a duplicate of item, allocated in pool.
svn_error_t * | svn_wc_parse_externals_description3 (apr_array_header_t **externals_p, const char *parent_directory, const char *desc, svn_boolean_t canonicalize_url, apr_pool_t *pool)
| If externals_p is non-NULL, set *externals_p to an array of svn_wc_external_item2_t * objects based on desc.
svn_error_t * | svn_wc_parse_externals_description2 (apr_array_header_t **externals_p, const char *parent_directory, const char *desc, apr_pool_t *pool)
| Similar to svn_wc_parse_externals_description3() with canonicalize_url set to `TRUE`, but returns an array of svn_wc_external_item_t * objects instead of svn_wc_external_item2_t * objects.
svn_error_t * | svn_wc_parse_externals_description (apr_hash_t **externals_p, const char *parent_directory, const char *desc, apr_pool_t *pool)
| Similar to svn_wc_parse_externals_description2(), but returns the parsed externals in a hash instead of an array.

## Typedef Documentation

typedef struct svn_wc_external_item2_t svn_wc_external_item2_t

One external item.

This usually represents one line from an svn:externals description but with the path and URL canonicalized.

In order to avoid backwards compatibility problems clients should use svn_wc_external_item_create() to allocate and initialize this structure instead of doing so themselves.

Since:
  New in 1.5.

typedef struct svn_wc_external_item_t svn_wc_external_item_t

One external item.

Similar to svn_wc_external_item2_t, except revision is interpreted as both the operational revision and the peg revision.

Deprecated:
  Provided for backward compatibility with the 1.4 API.

typedef svn_error_t*(* svn_wc_external_update_t)(void *baton, const char *local_abspath, const svn_string_t *old_val, const svn_string_t *new_val, svn_depth_t depth, apr_pool_t *scratch_pool)

Callback for external definitions updates.

local_abspath is the path on which the external definition was found. old_val and new_val are the before and after values of the SVN_PROP_EXTERNALS property. depth is the ambient depth of the working copy directory at local_abspath.

Since:
  New in 1.7.

Definition at line 688 of file svn_wc.h.

typedef struct svn_wc_traversal_info_t svn_wc_traversal_info_t

Traversal information is information gathered by a working copy crawl or update.

For example, the before and after values of the svn:externals property are important after an update, and since we're traversing the working tree anyway (a complete traversal during the initial crawl, and a traversal of changed paths during the checkout/update/switch), it makes sense to gather the property's values then instead of making a second pass.

New code should use the svn_wc_external_update_t callback instead.

Deprecated:
  Provided for backward compatibility with the 1.6 API.

Definition at line 707 of file svn_wc.h.

## Function Documentation

void svn_wc_edited_externals | ( | apr_hash_t ** | externals_old,
|  | apr_hash_t ** | externals_new,
|  | svn_wc_traversal_info_t * | traversal_info |
| ) |  |  |

Set *externals_old and *externals_new to hash tables representing changes to values of the svn:externals property on directories traversed by traversal_info.

traversal_info is obtained from svn_wc_init_traversal_info(), but is only useful after it has been passed through another function, such as svn_wc_crawl_revisions(), svn_wc_get_update_editor(), svn_wc_get_switch_editor(), etc.

Each hash maps `const char *` directory names onto `const char *` values of the externals property for that directory. The dir names are full paths -- that is, anchor plus target, not target alone. The values are not parsed, they are simply copied raw, and are never NULL: directories that acquired or lost the property are simply omitted from the appropriate table. Directories whose value of the property did not change show the same value in each hash.

The hashes, keys, and values have the same lifetime as traversal_info.

New code should use the svn_wc_external_update_t callback instead.

Deprecated:
  Provided for backward compatibility with the 1.6 API.

svn_wc_external_item2_t* svn_wc_external_item2_dup | ( | const svn_wc_external_item2_t * | item,
|  | apr_pool_t * | pool |
| ) |  |  |

Return a duplicate of item, allocated in pool.

No part of the new item will be shared with item.

Since:
  New in 1.5.

svn_error_t* svn_wc_external_item_create | ( | const svn_wc_external_item2_t ** | item,
|  | apr_pool_t * | pool |
| ) |  |  |

Initialize an external item.

Set *item to an external item object, allocated in pool.

In order to avoid backwards compatibility problems, this function is used to initialize and allocate the svn_wc_external_item2_t structure rather than doing so explicitly, as the size of this structure may change in the future.

The current implementation never returns error, but callers should still check for error, for compatibility with future versions.

Since:
  New in 1.5.

svn_wc_external_item_t* svn_wc_external_item_dup | ( | const svn_wc_external_item_t * | item,
|  | apr_pool_t * | pool |
| ) |  |  |

Return a duplicate of item, allocated in pool.

No part of the new item will be shared with item.

Since:
  New in 1.3.

Deprecated:
  Provided for backward compatibility with the 1.4 API.

svn_wc_traversal_info_t* svn_wc_init_traversal_info | ( | apr_pool_t * | pool | ) |

Return a new, empty traversal info object, allocated in pool.

New code should use the svn_wc_external_update_t callback instead.

Deprecated:
  Provided for backward compatibility with the 1.6 API.

svn_error_t* svn_wc_parse_externals_description | ( | apr_hash_t ** | externals_p,
|  | const char * | parent_directory,
|  | const char * | desc,
|  | apr_pool_t * | pool |
| ) |  |  |

Similar to svn_wc_parse_externals_description2(), but returns the parsed externals in a hash instead of an array.

This function should not be used, as storing the externals in a hash causes their order of evaluation to be not easily identifiable.

Deprecated:
  Provided for backward compatibility with the 1.0 API.

svn_error_t* svn_wc_parse_externals_description2 | ( | apr_array_header_t ** | externals_p,
|  | const char * | parent_directory,
|  | const char * | desc,
|  | apr_pool_t * | pool |
| ) |  |  |

Similar to svn_wc_parse_externals_description3() with canonicalize_url set to `TRUE`, but returns an array of svn_wc_external_item_t * objects instead of svn_wc_external_item2_t * objects.

Since:
  New in 1.1.

Deprecated:
  Provided for backward compatibility with the 1.4 API.

svn_error_t* svn_wc_parse_externals_description3 | ( | apr_array_header_t ** | externals_p,
|  | const char * | parent_directory,
|  | const char * | desc,
|  | svn_boolean_t | canonicalize_url,
|  | apr_pool_t * | pool |
| ) |  |  |

If externals_p is non-NULL, set *externals_p to an array of svn_wc_external_item2_t * objects based on desc.

If the format of desc is invalid, don't touch *externals_p and return SVN_ERR_CLIENT_INVALID_EXTERNALS_DESCRIPTION. Thus, if you just want to check the validity of an externals description, and don't care about the parsed result, pass NULL for externals_p.

The format of desc is the same as for values of the directory property SVN_PROP_EXTERNALS. Look there for more details.

If canonicalize_url is `TRUE`, canonicalize the url member of those objects. If the url member refers to an absolute URL, it will be canonicalized as URL consistent with the way URLs are canonicalized throughout the Subversion API. If, however, the url member makes use of the recognized (and proprietary) relative URL syntax, "canonicalization" is a less easily-defined concept which may even result in munging the relative URL syntax beyond recognition. You've been warned.

Allocate the table, keys, and values in pool.

Use parent_directory only in constructing error strings.

Since:
  New in 1.5.

void svn_wc_traversed_depths | ( | apr_hash_t ** | depths,
|  | svn_wc_traversal_info_t * | traversal_info |
| ) |  |  |

Set *depths to a hash table mapping `const char *` directory names (directories traversed by traversal_info) to `const char *` values (the depths of those directories, as converted by svn_depth_to_word()).

traversal_info is obtained from svn_wc_init_traversal_info(), but is only useful after it has been passed through another function, such as svn_wc_crawl_revisions(), svn_wc_get_update_editor(), svn_wc_get_switch_editor(), etc.

The dir names are full paths -- that is, anchor plus target, not target alone. The values are not allocated, they are static constant strings. Although the values are never NULL, not all directories traversed are necessarily listed. For example, directories which did not have an svn:externals property set or modified are not included.

The hashes and keys have the same lifetime as traversal_info.

New code should use the svn_wc_external_update_t callback instead.

Since:
  New in 1.5.

Deprecated:
  Provided for backward compatibility with the 1.6 API.

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines