diff options
Diffstat (limited to 'libccnx-portal/ccnx/api/ccnx_Portal/ccnx_PortalStack.h')
| -rwxr-xr-x | libccnx-portal/ccnx/api/ccnx_Portal/ccnx_PortalStack.h | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/libccnx-portal/ccnx/api/ccnx_Portal/ccnx_PortalStack.h b/libccnx-portal/ccnx/api/ccnx_Portal/ccnx_PortalStack.h new file mode 100755 index 00000000..b119213a --- /dev/null +++ b/libccnx-portal/ccnx/api/ccnx_Portal/ccnx_PortalStack.h @@ -0,0 +1,330 @@ +/* + * 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_PortalStack.h + * @brief A polymorphic interface to different Portal Stack implementations. + * + */ +#ifndef CCNx_Portal_API_ccnx_PortalImplementation_h +#define CCNx_Portal_API_ccnx_PortalImplementation_h + +struct CCNxPortalStack; +/** + * @typedef CCNxPortalStack + * @brief A set of functions and state for the Portal instance. + */ +typedef struct CCNxPortalStack CCNxPortalStack; + +#include <parc/algol/parc_Properties.h> +#include <ccnx/api/ccnx_Portal/ccnx_PortalFactory.h> + +/** + * Create function for a `CCNxPortalStack` + * + * @param [in] factory An instance of a {@link CCNxPortalFactory}. + * @param [in] start A pointer to a function that takes `*privateData` as a parameter. + * @param [in] stop A pointer to a function that takes `*privateData` as a parameter. + * @param [in] receiveFunction A pointer to a function that takes `*privateData` as a parameter and returns a pointer to a {@link CCNxMetaMessage}. + * @param [in] send A pointer to a function that takes `*privateData` and `*portalMessage` as parameters. + * @param [in] listen A pointer to a function that takes `*privateData` and a {@link CCNxName} as parameters. + * @param [in] ignore A pointer to a function that takes `*privateData` and a {@link CCNxName} as parameters. + * @param [in] getFileId A pointer to a function that takes `*privateData` as a parameter and returns an `int`. + * @param [in] setAttributes A pointer to a function that takes `*privateData` and a {@link CCNxPortalAttributes} as parameters. + * @param [in] getAttributes A pointer to a function that takes `*privateData` as a parameter and returns an instance of `CCNxPortalAttributes`. + * @param [in] privateData A pointer to some data. + * @param [in] releasePrivateData A pointer to a function that takes `**privateData` as a parameter. + * + * @return A pointer to a new `CCNxPortalStack`. + * + */ +CCNxPortalStack * +ccnxPortalStack_Create(const CCNxPortalFactory *factory, + const CCNxPortalAttributes *attributes, + void (*start)(void *privateData), + void (*stop)(void *privateData), + CCNxMetaMessage *(*receive)(void *privateData, const CCNxStackTimeout *microSeconds), + bool (*send)(void *privateData, const CCNxMetaMessage *message, const CCNxStackTimeout *microSeconds), + bool (*listen)(void *privateData, const CCNxName *name, const CCNxStackTimeout *microSeconds), + bool (*ignore)(void *privateData, const CCNxName *name, const CCNxStackTimeout *microSeconds), + int (*getFileId)(void *privateData), + bool (*setAttributes)(void *privateData, const CCNxPortalAttributes *attributes), + CCNxPortalAttributes * (*getAttributes)(void *privateData), + void *privateData, + void (*releasePrivateData)(void **privateData)); + +/** + * Increase the number of references to a `PARCBuffer`. + * + * Note that new `PARCBuffer` is not created, + * only that the given `PARCBuffer` reference count is incremented. + * Discard the reference by invoking `parcBuffer_Release`. + * + * @param [in] portal A pointer to a valid CCNxPortalStack instance. + * + * @return The input `CCNxPortalStack` pointer. + * + * Example: + * @code + * { + * PARCBuffer *x = parcBuffer_Allocate(10); + * + * PARCBuffer *x_2 = parcBuffer_Acquire(x); + * + * parcBuffer_Release(&x); + * parcBuffer_Release(&x_2); + * } + * @endcode + */ +CCNxPortalStack *ccnxPortalStack_Acquire(const CCNxPortalStack *portal); + +/** + * Release a previously acquired reference to the specified `CCNxPortalStack` 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] portalPtr A pointer to a pointer to a `CCNxPortalStack` instance to be released. + * + * Example: + * @code + * { + * CCNxPortalStack *stack = ccnxPortalStack_Create(...); + * + * ccnxPortalStack_Release(&stack); + * } + * @endcode + * + * @see {@link ccnxPortalStack_Create} + * @see {@link ccnxPortalStack_Acquire} + */ +void ccnxPortalStack_Release(CCNxPortalStack **portalPtr); + +/** + * Release a `CCNxPortalStack` reference. + * + * Only the last invocation where the reference count is decremented to zero, + * will actually destroy the `CCNxPortalStack`. + * + * @param [in,out] instancePtr is a pointer to the `CCNxPortalStack` reference to be released. + * + * Example: + * @code + * <#example#> + * @endcode + */ +void ccnxPortalStack_Release(CCNxPortalStack **instancePtr); + +/** + * Start a `CCNxPortalStack` + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack` + * + * @return `true` if stack started successfully, else `false`. + * + * Example: + * @code + * <#example#> + * @endcode + */ +bool ccnxPortalStack_Start(const CCNxPortalStack *implementation); + +/** + * Stop a `CCNxPortalStack` + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack` + * + * @return `true` if stack started successfully, else `false`. + * + * Example: + * @code + * <#example#> + * @endcode + */ +bool ccnxPortalStack_Stop(const CCNxPortalStack *implementation); + +/** + * Receive a message from a `CCNxPortalStack` + * + * @param [in] portalStack A pointer to an instance of `CCNxPortalStack` + * @param [in] microSeconds A pointer to a `struct timeval` or NULL indicating no timeout. + * + * @return An instance of {@link CCNxMetaMessage}. + * + * Example: + * @code + * <#example#> + * @endcode + */ +CCNxMetaMessage *ccnxPortalStack_Receive(const CCNxPortalStack *portalStack, const CCNxStackTimeout *microSeconds); + +/** + * Send a message through a `CCNxPortalStack` + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack`. + * @param [in] portalMessage A pointer to an instance of `CCNxMetaMessage` to send. + * + * @return `true` if message sent successfully, else `false`. + * + * Example: + * @code + * <#example#> + * @endcode + */ +bool ccnxPortalStack_Send(const CCNxPortalStack *implementation, const CCNxMetaMessage *portalMessage, const CCNxStackTimeout *microSeconds); + +/** + * Set the attributes on a `CCNxPortalStack`. + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack`. + * @param [in] attributes A pointer to an instance of `CCNxPortalAttributes`. + * @return `true` if attributes set successfully, else `false`. + * + * Example: + * @code + * <#example#> + * @endcode + */ + +bool ccnxPortalStack_SetAttributes(const CCNxPortalStack *implementation, const CCNxPortalAttributes *attributes); + +/** + * Get the attributes from a `CCNxPortalStack`. + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack`. + * @return A pointer to an instance of `CCNxPortalAttributes` associated with the @p implementation. + * + * Example: + * @code + * <#example#> + * @endcode + */ +const CCNxPortalAttributes *ccnxPortalStack_GetAttributes(const CCNxPortalStack *implementation); + +/** + * Listen for @p name on the @p implementation. + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack`. + * @param [in] name A pointer to an instance of {@link CCNxName} to listen for. + * + * @return `true` if listen started successfully, else `false`. + * + * Example: + * @code + * <#example#> + * @endcode + */ +bool ccnxPortalStack_Listen(const CCNxPortalStack *implementation, const CCNxName *name, const CCNxStackTimeout *microSeconds); +/** + * Ignore (stop listening for) @p name on the @p implementation. + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack`. + * @param [in] name A pointer to an instance of {@link CCNxName} to listen for. + * + * @return `true` if ignore was successful, else `false`. + * + * Example: + * @code + * <#example#> + * @endcode + */ + +bool ccnxPortalStack_Ignore(const CCNxPortalStack *implementation, const CCNxName *name, const CCNxStackTimeout *microSeconds); +/** + * Get the file ID for @p implementation. + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack`. + * + * @return `int` The file ID. + * + * Example: + * @code + * <#example#> + * @endcode + */ +int ccnxPortalStack_GetFileId(const CCNxPortalStack *implementation); + +/** + * Get the {@link PARCKeyId} associated with the @p implementation. + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack`. + * + * @return A pointer to the `PARCKeyId`. + * + * Example: + * @code + * <#example#> + * @endcode + */ +const PARCKeyId *ccnxPortalStack_GetKeyId(const CCNxPortalStack *implementation); + +/** + * Get the error code for the most recent operation. + * + * @param [in] implementation A pointer to an instance of `CCNxPortalStack`. + * + * @return A value corresponding to the UNIX `errno` see `sys/errno.h` + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +int ccnxPortalStack_GetErrorCode(const CCNxPortalStack *implementation); + +/** + * <#One Line Description#> + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in#> | <#out#> | <#in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +PARCProperties *ccnxPortalStack_GetProperties(const CCNxPortalStack *portalStack); + +/** + * <#One Line Description#> + * + * <#Paragraphs Of Explanation#> + * + * @param [in] portalStack <#description#> + * @param [in] name <#description#> + * @param [in] defaultValue <#description#> + * + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +const char *ccnxPortalStack_GetProperty(const CCNxPortalStack *portalStack, const char *restrict name, const char *restrict defaultValue); +#endif |