summaryrefslogtreecommitdiffstats
path: root/hicn-light/src/io/addressPair.h
diff options
context:
space:
mode:
Diffstat (limited to 'hicn-light/src/io/addressPair.h')
-rwxr-xr-xhicn-light/src/io/addressPair.h128
1 files changed, 128 insertions, 0 deletions
diff --git a/hicn-light/src/io/addressPair.h b/hicn-light/src/io/addressPair.h
new file mode 100755
index 000000000..5152267b6
--- /dev/null
+++ b/hicn-light/src/io/addressPair.h
@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2017-2019 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.
+ */
+
+/**
+ * Used to identify a connection between a specific local address and
+ * a specific remote address.
+ */
+
+#ifndef address_Pair_h
+#define address_Pair_h
+
+#include <src/utils/address.h>
+
+struct address_pair;
+typedef struct address_pair AddressPair;
+
+/**
+ * @function addressPair_Create
+ * @abstract Creates and address pair. There is no restriction on the address
+ * types.
+ * @discussion
+ * Creates an ordered pair of addresses, where the first is considered the
+ * "local" address and the second is the "remote" address. Those designations
+ * are purely a convention used to name them, and does not imply any specifici
+ * types of operations.
+ *
+ * The two addresses may be of any address types (e.g. IPv4, IPv6, Local,
+ * Ethernet). However, some functions that use an AddressPair may require that
+ * the local and remote addresses be the same type.
+ *
+ */
+AddressPair *addressPair_Create(const Address *local, const Address *remote);
+
+/**
+ * Returns a reference counted copy of the address pair
+ *
+ * Increments the reference count and returns the same address pair
+ *
+ * @param [in] addressPair An allocated address pair
+ *
+ * @retval non-null A reference counted copy
+ * @retval null An error
+ */
+AddressPair *addressPair_Acquire(const AddressPair *addressPair);
+
+/**
+ * Releases a reference count to the object
+ *
+ * Decrements the reference count and destroys the object when it reaches 0.
+ */
+void addressPair_Release(AddressPair **pairPtr);
+
+/**
+ * Determine if two AddressPair instances are equal.
+ *
+ * Two AddressPair instances are equal if, and only if, the local and remote
+ * addresses are identical. Equality is determined by addressEquals(a->local,
+ * b->local) and Adress_Equals(a->remote, b->remote).
+ *
+ * The following equivalence relations on non-null `AddressPair` instances are
+ * maintained:
+ *
+ * * It is reflexive: for any non-null reference value x,
+ * `AddressPair_Equals(x, x)` must return true.
+ *
+ * * It is symmetric: for any non-null reference values x and y,
+ * `addressPair_Equals(x, y)` must return true if and only if
+ * `addressPair_Equals(y, x)` returns true.
+ *
+ * * It is transitive: for any non-null reference values x, y, and z, if
+ * `addressPair_Equals(x, y)` returns true and
+ * `addressPair_Equals(y, z)` returns true,
+ * then `addressPair_Equals(x, z)` must return true.
+ *
+ * * It is consistent: for any non-null reference values x and y, multiple
+ * invocations of `addressPair_Equals(x, y)` consistently return true or
+ * consistently return false.
+ *
+ * * For any non-null reference value x, `addressPair_Equals(x, NULL)` must
+ * return false.
+ *
+ * @param a A pointer to a `AddressPair` instance.
+ * @param b A pointer to a `AddressPair` instance.
+ * @return true if the two `AddressPair` instances are equal.
+ */
+bool addressPair_Equals(const AddressPair *a, const AddressPair *b);
+
+/**
+ * @function addressPair_EqualsAddresses
+ * @abstract As AddressEquals, but "b" is broken out
+ * @discussion
+ * Equality is determined by addressEquals(a->local, local) and
+ * Adress_Equals(a->remote, remote).
+ */
+bool addressPair_EqualsAddresses(const AddressPair *a, const Address *local,
+ const Address *remote);
+
+const Address *addressPair_GetLocal(const AddressPair *pair);
+
+const Address *addressPair_GetRemote(const AddressPair *pair);
+
+/**
+ * @function addressPair_HashCode
+ * @abstract Hash useful for tables. Consistent with Equals.
+ * @discussion
+ * Returns a non-cryptographic hash that is consistent with equals. That is,
+ * if a == b, then hash(a) == hash(b).
+ */
+PARCHashCode addressPair_HashCode(const AddressPair *pair);
+
+/**
+ * @function addressPair_ToString
+ * @abstract Human readable string representation. Caller must use free(3).
+ */
+char *addressPair_ToString(const AddressPair *pair);
+#endif // address_Pair_h