Changeset b69ceea in mainline for uspace/lib/net/generic/packet_client.c

Timestamp:

2010-10-15T21:40:36Z (14 years ago)

Author:

Jakub Jermar <jakub@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

614d065

Parents:

b934e43

Message:

Cleanup packet_{client,remote}.[ch].

File:

• uspace/lib/net/generic/packet_client.c (modified) (11 diffs)

uspace/lib/net/generic/packet_client.c

@@ -27 +27 @@
  */
 
-/** @addtogroup packet
- *  @{
+/** @addtogroup libnet
+ * @{
  */
 
 /** @file
- *  Packet client implementation.
+ * Packet client implementation.
  */
 
@@ -38 +38 @@
 #include <mem.h>
 #include <unistd.h>
-
 #include <sys/mman.h>
 
 #include <packet_client.h>
+#include <packet_remote.h>
 
 #include <net/packet.h>
 #include <net/packet_header.h>
 
-int packet_copy_data(packet_t packet, const void * data, size_t length)
+/** Copies the specified data to the beginning of the actual packet content.
+ *
+ * Pushes the content end if needed.
+ *
+ * @param[in] packet    The packet to be filled.
+ * @param[in] data      The data to be copied.
+ * @param[in] length    The length of the copied data.
+ * @returns             EOK on success.
+ * @returns             EINVAL if the packet is not valid.
+ * @returns             ENOMEM if there is not enough memory left.
+ */
+int packet_copy_data(packet_t packet, const void *data, size_t length)
 {
         if (!packet_is_valid(packet))
@@ -61 +72 @@
 }
 
+/** Allocates the specified space right before the actual packet content and
+ * returns its pointer.
+ *
+ * @param[in] packet    The packet to be used.
+ * @param[in] length    The space length to be allocated at the beginning of the
+ *                      packet content.
+ * @returns             The pointer to the allocated memory.
+ * @returns             NULL if there is not enough memory left.
+ */
 void *packet_prefix(packet_t packet, size_t length)
 {
@@ -73 +93 @@
 }
 
+/** Allocates the specified space right after the actual packet content and
+ * returns its pointer.
+ *
+ * @param[in] packet    The packet to be used.
+ * @param[in] length    The space length to be allocated at the end of the
+ *                       packet content.
+ * @returns             The pointer to the allocated memory.
+ * @returns             NULL if there is not enough memory left.
+ */
 void *packet_suffix(packet_t packet, size_t length)
 {
@@ -84 +113 @@
 }
 
+/** Trims the actual packet content by the specified prefix and suffix lengths.
+ *
+ * @param[in] packet    The packet to be trimmed.
+ * @param[in] prefix    The prefix length to be removed from the beginning of
+ *                      the packet content.
+ * @param[in] suffix    The suffix length to be removed from the end of the
+ *                      packet content.
+ * @returns             EOK on success.
+ * @returns             EINVAL if the packet is not valid.
+ * @returns             ENOMEM if there is not enough memory left.
+ */
 int packet_trim(packet_t packet, size_t prefix, size_t suffix)
 {
@@ -97 +137 @@
 }
 
+/** Returns the packet identifier.
+ *
+ * @param[in] packet    The packet.
+ * @returns             The packet identifier.
+ * @returns             Zero if the packet is not valid.
+ */
 packet_id_t packet_get_id(const packet_t packet)
 {
@@ -102 +148 @@
 }
 
-int packet_get_addr(const packet_t packet, uint8_t ** src, uint8_t ** dest)
+/** Returns the stored packet addresses and their length.
+ *
+ * @param[in] packet    The packet.
+ * @param[out] src      The source address. May be NULL if not desired.
+ * @param[out] dest     The destination address. May be NULL if not desired.
+ * @returns             The stored addresses length.
+ * @returns             Zero if the addresses are not present.
+ * @returns             EINVAL if the packet is not valid.
+ */
+int packet_get_addr(const packet_t packet, uint8_t **src, uint8_t **dest)
 {
         if (!packet_is_valid(packet))
@@ -116 +171 @@
 }
 
+/** Returns the packet content length.
+ *
+ * @param[in] packet    The packet.
+ * @returns             The packet content length in bytes.
+ * @returns             Zero if the packet is not valid.
+ */
 size_t packet_get_data_length(const packet_t packet)
 {
@@ -124 +185 @@
 }
 
+/** Returns the pointer to the beginning of the packet content.
+ *
+ * @param[in] packet    The packet.
+ * @returns             The pointer to the beginning of the packet content.
+ * @returns             NULL if the packet is not valid.
+ */
 void *packet_get_data(const packet_t packet)
 {
@@ -132 +199 @@
 }
 
+/** Sets the packet addresses.
+ *
+ * @param[in] packet    The packet.
+ * @param[in] src       The new source address. May be NULL.
+ * @param[in] dest      The new destination address. May be NULL.
+ * @param[in] addr_len  The addresses length.
+ * @returns             EOK on success.
+ * @returns             EINVAL if the packet is not valid.
+ * @returns             ENOMEM if there is not enough memory left.
+ */
 int
-packet_set_addr(packet_t packet, const uint8_t * src, const uint8_t * dest,
+packet_set_addr(packet_t packet, const uint8_t *src, const uint8_t *dest,
     size_t addr_len)
 {
@@ -170 +247 @@
 }
 
+/** Returns the packet copy.
+ *
+ * Copies the addresses, data, order and metric values.
+ * Does not copy the queue placement.
+ *
+ * @param[in] phone     The packet server module phone.
+ * @param[in] packet    The original packet.
+ * @returns             The packet copy.
+ * @returns             NULL on error.
+ */
 packet_t packet_get_copy(int phone, packet_t packet)
 {