Merge "Initial commit: cframework. Longbow and Libparc" into cframework/master

1 files changed, 237 insertions, 0 deletions

diff --git a/libparc/parc/algol/parc_URIAuthority.h b/libparc/parc/algol/parc_URIAuthority.h
new file mode 100644
index 00000000..49d19734
--- /dev/null
+++ b/libparc/parc/algol/parc_URIAuthority.h
@@ -0,0 +1,237 @@
+/*
+ * Copyright (c) 2017 Cisco and/or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file parc_URIAuthority.h
+ * @ingroup networking
+ * @brief A Universal Resource Identifier (URI) Authority
+ *
+ */
+#ifndef libparc_parc_URIAuthority_h
+#define libparc_parc_URIAuthority_h
+
+#include <stdbool.h>
+
+struct parc_uri_authority;
+typedef struct parc_uri_authority PARCURIAuthority;
+
+/**
+ * Create a new `PARCURIAuthority` object.
+ *
+ * The new `PARCURIAuthority` object is empty.
+ *
+ * @return A pointer to a `PARCURIAuthority` instance.
+ *
+ * Example:
+ * @code
+ * {
+ *     PARCURIAuthority *auth = parcURIAuthority_Create();
+ *     ...
+ *     parcURIAuthority_Release(&auth);
+ * }
+ * @endcode
+ */
+PARCURIAuthority *parcURIAuthority_Create(void);
+
+/**
+ * Increase the number of references to a `PARCURIAuthority` instance.
+ *
+ * Note that new `PARCURIAuthority` is not created,
+ * only that the given `PARCURIAuthority` reference count is incremented.
+ * Discard the reference by invoking `parcURIAuthority_Release`.
+ *
+ * @param auth A pointer to the original instance.
+ * @return The value of the input parameter @p instance.
+ *
+ * Example:
+ * @code
+ * {
+ *     PARCURIAuthority *x = parcURIAuthority_Create();
+ *
+ *     PARCURIAuthority *x2 = parcURIAuthority_Acquire(x);
+ *
+ *     parcURIAuthority_Release(&x);
+ *     parcURIAuthority_Release(&x2);
+ * }
+ * @endcode
+ *
+ * @see parcURIAuthority_Release
+ */
+PARCURIAuthority *parcURIAuthority_Acquire(const PARCURIAuthority *auth);
+
+/**
+ * Release a previously acquired reference to the specified instance,
+ * decrementing the reference count for the instance.
+ *
+ * The pointer to the instance is set to NULL as a side-effect of this function.
+ *
+ * If the invocation causes the last reference to the instance to be released,
+ * the instance is deallocated and the instance's implementation will perform
+ * additional cleanup and release other privately held references.
+ *
+ * @param [in,out] authPtr A pointer to a pointer to the instance to release.
+ *
+ * Example:
+ * @code
+ * {
+ *     PARCURIAuthority *auth = parcURIAuthority_Create();
+ *
+ *     parcURIAuthority_Release(&auth);
+ * }
+ * @endcode
+ */
+void parcURIAuthority_Release(PARCURIAuthority **authPtr);
+
+/**
+ * Return true if two `PARCURIAuthority` instances are equal.
+ *
+ * The following equivalence relations on non-null `PARCURIAuthority` instances are maintained:
+ *
+ *   * It is reflexive: for any non-null reference value x, parcURIAuthority_Equals(x, x) must return true.
+ *
+ *   * It is symmetric: for any non-null reference values x and y, parcURIAuthority_Equals(x, y) must return true if and only if
+ *        parcURIAuthority_Equals(y x) returns true.
+ *
+ *   * It is transitive: for any non-null reference values x, y, and z, if
+ *        parcURIAuthority_Equals(x, y) returns true and
+ *        parcURIAuthority_Equals(y, z) returns true,
+ *        then  parcURIAuthority_Equals(x, z) must return true.
+ *
+ *   * It is consistent: for any non-null reference values x and y, multiple invocations of parcURIAuthority_Equals(x, y)
+ *         consistently return true or consistently return false.
+ *
+ *   * For any non-null reference value x, parcURIAuthority_Equals(x, NULL)) must return false.
+ *
+ * @param [in] authA The first `PARCURIAuthority` instance.
+ * @param [in] authB The second `PARCURIAuthority` instance.
+ *
+ * @return true the given `PARCURIAuthority` instances are equal.
+ * @return false the given `PARCURIAuthority` instances are not equal.
+ *
+ * Example:
+ * @code
+ * {
+ *     const char *uriString = "http://chris@parc.com:80";
+ *     PARCURI *uri = parcURI_Parse(uriString);
+ *     PARCURI_Authority *authority = parcURIAuthority_Parse(parcURI_GetAuthority(uri));
+ *     PARCURI_Authority *handle = parcURIAuthority_Acquire(authority);
+ *
+ *     if (parcURIAuthority_Equals(authority, handle)) {
+ *         printf("Authorities are equal.\n");
+ *     } else {
+ *         printf("Authorities are NOT equal.\n");
+ *     }
+ *
+ *     parcURIAuthority_Release(&uri);
+ *     parcURIAuthority_Release(&copy);
+ * }
+ * @endcode
+ */
+bool parcURIAuthority_Equals(const PARCURIAuthority *authA, const PARCURIAuthority *authB);
+
+/**
+ * Produce a `PARCURI_Authority` type from the authority string.
+ *
+ *   The returned value must be destroyed via {@link parcMemory_Deallocate}.
+ *
+ * @param [in] authority The authority string to parse.
+ *
+ * @return A newly allocated `PARCURI_Authority` string.
+ *
+ * Example:
+ * @code
+ * {
+ *     const char *uriString = "http://chris@parc.com:80";
+ *     PARCURI *uri = parcURI_Parse(uriString);
+ *
+ *     PARCURI_Authority *authority = parcURIAuthority_Parse(parcURI_GetAuthority(uri));
+ *     // use the authority
+ *
+ *     parcURIAuthority_Release(&authority);
+ *     parcURI_Release(&uri);
+ * }
+ * @endcode
+ */
+PARCURIAuthority *parcURIAuthority_Parse(const char *authority);
+
+/**
+ * Retrieve the user information from the given `PARCURI_Authority` instance.
+ *
+ * @param [in] authority The `PARCURI_Authority` instance being queried.
+ *
+ * @return The user info string component of the `PARCURI_Authority` instance. Copy the string prior to modification.
+ *
+ * Example:
+ * @code
+ * {
+ *     const char *uriString = "http://chris@parc.com:80";
+ *     PARCURI *uri = parcURI_Parse(uriString);
+ *
+ *     PARCURI_Authority *authority = parcURIAuthority_Parse(parcURI_GetAuthority(uri));
+ *     printf("User info: "%s\n", parcURIAuthority_GetUserInfo(authority));
+ *
+ *     parcURIAuthority_Release(&authority);
+ *     parcURI_Release(&uri);
+ * }
+ * @endcode
+ */
+const char *parcURIAuthority_GetUserInfo(const PARCURIAuthority *authority);
+
+/**
+ * Retrieve the host name from the given `PARCURI_Authority` instance.
+ *
+ * @param [in] authority The `PARCURI_Authority` instance being queried.
+ *
+ * @return The host name string component of the `PARCURI_Authority` instance. Copy the string prior to modification.
+ *
+ * Example:
+ * @code
+ * {
+ *     const char *uriString = "http://chris@parc.com:80";
+ *     PARCURI *uri = parcURI_Parse(uriString);
+ *
+ *     PARCURI_Authority *authority = parcURIAuthority_Parse(parcURI_GetAuthority(uri));
+ *     printf("Host name: "%s\n", parcURIAuthority_GetHostName(authority));
+ *
+ *     parcURIAuthority_Release(&authority);
+ *     parcURI_Release(&uri);
+ * }
+ * @endcode
+ */
+const char *parcURIAuthority_GetHostName(const PARCURIAuthority *authority);
+
+/**
+ * Retrieve the host port from the given `PARCURI_Authority` instance.
+ *
+ * @param [in] authority The `PARCURI_Authority` instance being queried.
+ *
+ * @return The host port string component of the `PARCURI_Authority` instance. Copy the string prior to modification.
+ *
+ * Example:
+ * @code
+ * {
+ *     const char *uriString = "http://chris@parc.com:80";
+ *     PARCURI *uri = parcURI_Parse(uriString);
+ *
+ *     PARCURI_Authority *authority = parcURIAuthority_Parse(parcURI_GetAuthority(uri));
+ *     printf("Host port: "%s\n", parcURIAuthority_GetPort(authority));
+ *
+ *     parcURIAuthority_Release(&authority);
+ *     parcURI_Release(&uri);
+ * }
+ * @endcode
+ */
+long parcURIAuthority_GetPort(const PARCURIAuthority *authority);
+#endif /* defined(libparc_parc_URIAuthority_h) */