1 files changed, 236 insertions, 0 deletions
diff --git a/libccnx-portal/ccnx/api/ccnx_Portal/ccnx_PortalFactory.h b/libccnx-portal/ccnx/api/ccnx_Portal/ccnx_PortalFactory.h
new file mode 100755
index 00000000..e021b92d
--- /dev/null
+++ b/libccnx-portal/ccnx/api/ccnx_Portal/ccnx_PortalFactory.h
@@ -0,0 +1,236 @@
+/*
+ * 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 ccnx_PortalFactory.h
+ * @brief An API for creating Portals.
+ *
+ */
+#ifndef CCNx_Portal_API_ccnx_PortalFactory_h
+#define CCNx_Portal_API_ccnx_PortalFactory_h
+
+struct CCNxPortalFactory;
+/**
+ * @typedef CCNxPortalFactory
+ * @brief A Portal factory.
+ */
+typedef struct CCNxPortalFactory CCNxPortalFactory;
+
+#include <parc/algol/parc_Properties.h>
+#include <parc/security/parc_Identity.h>
+#include <parc/security/parc_KeyId.h>
+
+#include <ccnx/transport/common/transport.h>
+#include <ccnx/transport/common/transport_MetaMessage.h>
+#include <ccnx/api/ccnx_Portal/ccnx_Portal.h>
+
+extern const char *CCNxPortalFactory_LocalRouterName;
+extern const char *CCNxPortalFactory_LocalForwarder;
+extern const char *CCNxPortalFactory_LocalRouterTimeout;
+
+/**
+ * Create a `CCNxPortalFactory` with the given {@link PARCIdentity}.
+ *
+ * If successful, a new reference to the given `PARCIdentity`
+ * instance is acquired and released when the result is eventually released
+ * via {@link ccnxPortalFactory_Release}.
+ * The caller must release its original reference.
+ *
+ * The given `PARCIdentity` is the identity used for interacting with the Transport Framework when creating a new stack.
+ * The default behaviour is that identity is also used for subsequent Content Object signing operations.
+ * It is permissable, however, to set a different identity,
+ * after a Portal API instance is created should its associated Transport Stack support setting a new identity.
+ *
+ * @param [in] identity A pointer to a `PARCIdentity` instance.
+ *
+ * @return non-NULL A pointer to a `CCNxPortalFactory` instance.
+ * @return NULL Memory could not be allocated.
+ *
+ * Example:
+ * @code
+ * {
+ *     char *subjectName = "An Example";
+ *     char *keystoreName = "keystore";
+ *     char *keystorePassword = "password";
+ *
+ *     bool success = parcPkcs12KeyStore_CreateFile(keystoreName, keystorePassword, subjectName, 1024, 30);
+ *
+ *     PARCIdentity *identity =
+ *         parcIdentity_Create(parcIdentityFile_Create(keystoreName, keystorePassword), PARCIdentityFileAsPARCIdentity);
+ *
+ *     CCNxPortalFactory *factory = ccnxPortalFactory_Create(identity);
+ *     parcIdentity_Release(&identity);
+ *
+ *     ccnxPortalFactory_Release(&factory);
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxPortalFactory_Acquire}
+ * @see {@link ccnxPortalFactory_Release}
+ */
+CCNxPortalFactory *ccnxPortalFactory_Create(const PARCIdentity *identity);
+
+/**
+ * Print a human readable representation of the given `CCNxPortalFactory` instance.
+ *
+ * @param [in] factory A pointer to the instance of `CCNxPortalFactory` to display.
+ * @param [in] indentation The level of indentation to use to pretty-print the output.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxPortalFactory *factory = ccnxPortalFactory_Create(...);
+ *
+ *     ccnxPortalFactory_Display(0, factory);
+ *
+ *     ccnxPortalFactory_Release(&factory);
+ * }
+ * @endcode
+ *
+ */
+void ccnxPortalFactory_Display(const CCNxPortalFactory *factory, int indentation);
+
+/**
+ * Increase the number of references to a `CCNxPortalFactory` instance.
+ *
+ * Note that new `CCNxPortalFactory` is not created,
+ * only that the given `CCNxPortalFactory` reference count is incremented.
+ * Discard the reference by invoking `ccnxPortalFactory_Release`.
+ *
+ * @param [in] instance A pointer to a valid `CCNxPortalFactory`.
+ *
+ * @return The value of the input parameter @p instance.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxPortalFactory *x = ccnxPortalFactory_Create(...);
+ *
+ *     CCNxPortalFactory *x2 = ccnxPortalFactory_Acquire(x);
+ *
+ *     ccnxPortalFactory_Release(&x);
+ *     ccnxPortalFactory_Release(&x2);
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxPortalFactory_Release}
+ */
+CCNxPortalFactory *ccnxPortalFactory_Acquire(const CCNxPortalFactory *instance);
+
+/**
+ * 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] factoryPtr A pointer to a pointer to the instance to release.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxPortalFactory *factory = ccnxPortalFactory_Create(...);
+ *
+ *     ccnxPortalFactory_Release(&factory);
+ * }
+ * @endcode
+ */
+void ccnxPortalFactory_Release(CCNxPortalFactory **factoryPtr);
+
+/**
+ * Get the {@link PARCIdentity} associated with the given `CCNxPortalFactory`.
+ *
+ * Note: a handle to the instance is not acquired, so you must not release it.
+ *
+ * @param [in] factory A pointer to a valid `CCNxPortalFactory`.
+ *
+ * @return A pointer to the internal `PARCIdentity` instance.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxPortalFactory *factory = ccnxPortalFactory_Create(...);
+ *
+ *     PARCIdentity *identity = ccnxPortalFactory_GetIdentity(factory);
+ *
+ *     ccnxPortalFactory_Release(&factory);
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxPortalFactory_Create}
+ */
+const PARCIdentity *ccnxPortalFactory_GetIdentity(const CCNxPortalFactory *factory);
+
+/**
+ * Get the `{@link PARCKeyId} of the {@link PARCIdentity} bound to the given CCNxPortalFactory.
+ *
+ * @param [in] factory A pointer to a valid `CCNxPortalFactory`.
+ *
+ * @return A pointer to the internal `PARCKeyId` instance.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxPortalFactory *factory = ccnxPortalFactory_Create(...);
+ *
+ *     PARCKeyId *keyId = ccnxPortalFactory_GetKeyId(factory);
+ *
+ *     ccnxPortalFactory_Release(&factory);
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxPortalFactory_Create}
+ */
+const PARCKeyId *ccnxPortalFactory_GetKeyId(const CCNxPortalFactory *factory);
+
+/**
+ * @typedef CCNxStackImpl
+ * @brief A function that creates a `CCNxPortal` given a factory and attributes.
+ */
+typedef CCNxPortal *(CCNxStackImpl)(const CCNxPortalFactory *factory, const CCNxPortalAttributes *attributes);
+
+/**
+ * Create an {@link CCNxPortal} instance of the specified communication type, protocol and attributes.
+ *
+ * @param [in] factory A pointer to a CCNxPortal factory to use to create the instance.
+ * @param [in,out] stackImplementation A pointer to a function initializing the protocol implementation.
+ *
+ * @return NULL An error occurred in creating the instance. See the value of `errno`
+ * @return non-NULL A pointer to a valid `CCNxPortal` instance.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxPortal *portal = ccnxPortalFactory_CreatePortal(factory, ccnxPortalRTA_Message);
+ *
+ *     ccnxPortal_Release(&portal);
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxPortal_Release}
+ */
+CCNxPortal *ccnxPortalFactory_CreatePortal(const CCNxPortalFactory *factory, CCNxStackImpl *stackImplementation);
+
+PARCProperties *ccnxPortalFactory_GetProperties(const CCNxPortalFactory *factory);
+
+const char *ccnxPortalFactory_GetProperty(const CCNxPortalFactory *factory, const char *restrict name, const char *restrict defaultValue);
+
+void ccnxPortalFactory_SetProperty(const CCNxPortalFactory *factory, const char *restrict name, const char *restrict value);
+
+#endif  // CCNx_Portal_API_ccnx_Portal_h
+