Add nsurl_ref for copying, replace nsurl_destroy with nsurl_unref, and add nsurl_access for accessing a pointer to string data internal to the NetSurf URL object.

svn path=/trunk/netsurf/; revision=12861

utils/nsurl.h

@@ -63,12 +63,24 @@ nserror nsurl_create(const char const *url_s, nsurl **url);
 
 
 /**
- * Destroy a NetSurf URL object
+ * Increment the reference count to a NetSurf URL object
  *
- * \param url	  NetSurf URL to destroy
+ * \param url	  NetSurf URL to create another reference to
- * \return NSERROR_OK on success, appropriate error otherwise
+ * \return The NetSurf URL pointer to use as the copy
+ *
+ * Use this when copying a NetSurf URL into a persistent data structure.
  */
-nserror nsurl_destroy(nsurl *url);
+nsurl *nsurl_ref(nsurl *url);
+
+
+/**
+ * Drop a reference to a NetSurf URL object
+ *
+ * \param url	  NetSurf URL to drop reference to
+ *
+ * When the reference count reaches zero then the NetSurf URL will be destroyed
+ */
+void nsurl_unref(nsurl *url);
 
 
 /**
@@ -112,6 +124,27 @@ nserror nsurl_get(const nsurl *url, nsurl_component parts,
 		char **url_s, size_t *url_l);
 
 
+/**
+ * Access a URL (section) as a string, from a NetSurf URL object
+ *
+ * \param url	  NetSurf URL to retrieve a string pointer for.
+ * \param parts	  The required URL components.
+ * \param url_l	  Returns length of returned string
+ * \return the required string
+ *
+ * If return value != NSERROR_OK, nothing will be returned in url_s or url_l.
+ *
+ * The string returned in is owned by the NetSurf URL object.  It will die
+ * with the NetSurf URL object.  Keep a reference to the URL if you need it.
+ *
+ * Required URL components must be consecutive.  Only when NSURL_WITH_FRAGMENT
+ * is passed as the parts param is a trailing '\0' guaranteed.
+ *
+ * The length returned in url_l excludes any trailing '\0'.
+ */
+char *nsurl_access(const nsurl *url, nsurl_component parts, size_t *url_l);
+
+
 /**
  * Join a base url to a relative link part, creating a new NetSurf URL object
  *