Ignore:
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:
1 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/net/include/packet_client.h

    rb934e43 rb69ceea  
    2727 */
    2828
    29 /** @addtogroup packet
     29/** @addtogroup libnet
    3030 *  @{
    3131 */
    3232
    3333/** @file
    34  *  Packet client.
    35  *  The hosting module has to be compiled with both the packet.c and the packet_client.c source files.
    36  *  To function correctly, initialization of the packet map by the pm_init() function has to happen at the first place.
    37  *  The module should not send the packet messages to the packet server but use the functions provided.
    38  *  The packet map should be released by the pm_destroy() function during the module termination.
    39  *  The packets and the packet queues can't be locked at all.
    40  *  The processing modules should process them sequentially -&nbsp;by passing the packets to the next module and stopping using the passed ones.
    41  *  @see packet.h
     34 * Packet client.
     35 *
     36 * To function correctly, initialization of the packet map by the pm_init()
     37 * function has to happen at the first place. The module should not send the
     38 * packet messages to the packet server but use the functions provided. The
     39 * packet map should be released by the pm_destroy() function during the module
     40 * termination. The packets and the packet queues can't be locked at all. The
     41 * processing modules should process them sequentially - by passing the packets
     42 * to the next module and stopping using the passed ones.
     43 *
     44 * @see packet.h
    4245 */
    4346
    44 #ifndef __NET_PACKET_CLIENT_H__
    45 #define __NET_PACKET_CLIENT_H__
     47#ifndef LIBNET_PACKET_CLIENT_H_
     48#define LIBNET_PACKET_CLIENT_H_
    4649
    4750#include <net/packet.h>
    4851
    49 /** @name Packet client interface
    50  */
     52/** @name Packet client interface */
    5153/*@{*/
    5254
    53 /** Allocates the specified type right before the actual packet content and returns its pointer.
    54  *  The wrapper of the packet_prepend() function.
    55  *  @param[in] packet The packet to be used.
    56  *  @param[in] type The type to be allocated at the beginning of the packet content.
    57  *  @returns The typed pointer to the allocated memory.
    58  *  @returns NULL if the packet is not valid.
    59  *  @returns NULL if there is not enough memory left.
     55/** Allocates the specified type right before the actual packet content and
     56 * returns its pointer.
     57 *
     58 * The wrapper of the packet_prepend() function.
     59 *
     60 * @param[in] packet    The packet to be used.
     61 * @param[in] type      The type to be allocated at the beginning of the packet
     62 *                      content.
     63 * @returns             The typed pointer to the allocated memory.
     64 * @returns             NULL if the packet is not valid.
     65 * @returns             NULL if there is not enough memory left.
    6066 */
    61 #define PACKET_PREFIX(packet, type)     (type *) packet_prefix((packet), sizeof(type))
     67#define PACKET_PREFIX(packet, type) \
     68        (type *) packet_prefix((packet), sizeof(type))
    6269
    63 /** Allocates the specified type right after the actual packet content and returns its pointer.
    64  *  The wrapper of the packet_append() function.
    65  *  @param[in] packet The packet to be used.
    66  *  @param[in] type The type to be allocated at the end of the packet content.
    67  *  @returns The typed pointer to the allocated memory.
    68  *  @returns NULL if the packet is not valid.
    69  *  @returns NULL if there is not enough memory left.
     70/** Allocates the specified type right after the actual packet content and
     71 * returns its pointer.
     72 *
     73 * The wrapper of the packet_append() function.
     74 *
     75 * @param[in] packet    The packet to be used.
     76 * @param[in] type      The type to be allocated at the end of the packet
     77 *                      content.
     78 * @returns             The typed pointer to the allocated memory.
     79 * @returns             NULL if the packet is not valid.
     80 * @returns             NULL if there is not enough memory left.
    7081 */
    71 #define PACKET_SUFFIX(packet, type)     (type *) packet_suffix((packet), sizeof(type))
     82#define PACKET_SUFFIX(packet, type) \
     83        (type *) packet_suffix((packet), sizeof(type))
    7284
    7385/** Trims the actual packet content by the specified prefix and suffix types.
    74  *  The wrapper of the packet_trim() function.
    75  *  @param[in] packet The packet to be trimmed.
    76  *  @param[in] prefix The type of the prefix to be removed from the beginning of the packet content.
    77  *  @param[in] suffix The type of the suffix to be removed from the end of the packet content.
    78  *  @returns EOK on success.
    79  *  @returns EINVAL if the packet is not valid.
    80  *  @returns ENOMEM if there is not enough memory left.
     86 *
     87 * The wrapper of the packet_trim() function.
     88 *
     89 * @param[in] packet    The packet to be trimmed.
     90 * @param[in] prefix    The type of the prefix to be removed from the beginning
     91 *                      of the packet content.
     92 * @param[in] suffix    The type of the suffix to be removed from the end of
     93 *                      the packet content.
     94 * @returns             EOK on success.
     95 * @returns             EINVAL if the packet is not valid.
     96 * @returns             ENOMEM if there is not enough memory left.
    8197 */
    82 #define PACKET_TRIM(packet, prefix, suffix)     packet_trim((packet), sizeof(prefix), sizeof(suffix))
     98#define PACKET_TRIM(packet, prefix, suffix) \
     99        packet_trim((packet), sizeof(prefix), sizeof(suffix))
    83100
    84 /** Allocates the specified space right before the actual packet content and returns its pointer.
    85  *  @param[in] packet The packet to be used.
    86  *  @param[in] length The space length to be allocated at the beginning of the packet content.
    87  *  @returns The pointer to the allocated memory.
    88  *  @returns NULL if there is not enough memory left.
    89  */
    90 extern void * packet_prefix(packet_t packet, size_t length);
    91 
    92 /** Allocates the specified space right after the actual packet content and returns its pointer.
    93  *  @param[in] packet The packet to be used.
    94  *  @param[in] length The space length to be allocated at the end of the packet content.
    95  *  @returns The pointer to the allocated memory.
    96  *  @returns NULL if there is not enough memory left.
    97  */
    98 extern void * packet_suffix(packet_t packet, size_t length);
    99 
    100 /** Trims the actual packet content by the specified prefix and suffix lengths.
    101  *  @param[in] packet The packet to be trimmed.
    102  *  @param[in] prefix The prefix length to be removed from the beginning of the packet content.
    103  *  @param[in] suffix The suffix length to be removed from the end of the packet content.
    104  *  @returns EOK on success.
    105  *  @returns EINVAL if the packet is not valid.
    106  *  @returns ENOMEM if there is not enough memory left.
    107  */
    108 extern int packet_trim(packet_t packet, size_t prefix, size_t suffix);
    109 
    110 /** Copies the specified data to the beginning of the actual packet content.
    111  *  Pushes the content end if needed.
    112  *  @param[in] packet The packet to be filled.
    113  *  @param[in] data The data to be copied.
    114  *  @param[in] length The length of the copied data.
    115  *  @returns EOK on success.
    116  *  @returns EINVAL if the packet is not valid.
    117  *  @returns ENOMEM if there is not enough memory left.
    118  */
    119 extern int packet_copy_data(packet_t packet, const void * data, size_t length);
    120 
    121 /** Returns the packet identifier.
    122  *  @param[in] packet The packet.
    123  *  @returns The packet identifier.
    124  *  @returns Zero (0) if the packet is not valid.
    125  */
    126 extern packet_id_t packet_get_id(const packet_t packet);
    127 
    128 /** Returns the packet content length.
    129  *  @param[in] packet The packet.
    130  *  @returns The packet content length in bytes.
    131  *  @returns Zero (0) if the packet is not valid.
    132  */
    133 extern size_t packet_get_data_length(const packet_t packet);
    134 
    135 /** Returns the pointer to the beginning of the packet content.
    136  *  @param[in] packet The packet.
    137  *  @returns The pointer to the beginning of the packet content.
    138  *  @returns NULL if the packet is not valid.
    139  */
    140 extern void * packet_get_data(const packet_t packet);
    141 
    142 /** Returns the stored packet addresses and their length.
    143  *  @param[in] packet The packet.
    144  *  @param[out] src The source address. May be NULL if not desired.
    145  *  @param[out] dest The destination address. May be NULL if not desired.
    146  *  @returns The stored addresses length.
    147  *  @returns Zero (0) if the addresses are not present.
    148  *  @returns EINVAL if the packet is not valid.
    149  */
    150 extern int packet_get_addr(const packet_t packet, uint8_t ** src, uint8_t ** dest);
    151 
    152 /** Sets the packet addresses.
    153  *  @param[in] packet The packet.
    154  *  @param[in] src The new source address. May be NULL.
    155  *  @param[in] dest The new destination address. May be NULL.
    156  *  @param[in] addr_len The addresses length.
    157  *  @returns EOK on success.
    158  *  @returns EINVAL if the packet is not valid.
    159  *  @returns ENOMEM if there is not enough memory left.
    160  */
    161 extern int packet_set_addr(packet_t packet, const uint8_t * src, const uint8_t * dest, size_t addr_len);
    162 
    163 /** Translates the packet identifier to the packet reference.
    164  *  Tries to find mapping first.
    165  *  Contacts the packet server to share the packet if the mapping is not present.
    166  *  @param[in] phone The packet server module phone.
    167  *  @param[out] packet The packet reference.
    168  *  @param[in] packet_id The packet identifier.
    169  *  @returns EOK on success.
    170  *  @returns EINVAL if the packet parameter is NULL.
    171  *  @returns Other error codes as defined for the NET_PACKET_GET_SIZE message.
    172  *  @returns Other error codes as defined for the packet_return() function.
    173  */
    174 extern int packet_translate_remote(int phone, packet_ref packet, packet_id_t packet_id);
    175 
    176 /** Obtains the packet of the given dimensions.
    177  *  Contacts the packet server to return the appropriate packet.
    178  *  @param[in] phone The packet server module phone.
    179  *  @param[in] addr_len The source and destination addresses maximal length in bytes.
    180  *  @param[in] max_prefix The maximal prefix length in bytes.
    181  *  @param[in] max_content The maximal content length in bytes.
    182  *  @param[in] max_suffix The maximal suffix length in bytes.
    183  *  @returns The packet reference.
    184  *  @returns NULL on error.
    185  */
    186 extern packet_t packet_get_4_remote(int phone, size_t max_content, size_t addr_len, size_t max_prefix, size_t max_suffix);
    187 
    188 /** Obtains the packet of the given content size.
    189  *  Contacts the packet server to return the appropriate packet.
    190  *  @param[in] phone The packet server module phone.
    191  *  @param[in] content The maximal content length in bytes.
    192  *  @returns The packet reference.
    193  *  @returns NULL on error.
    194  */
    195 extern packet_t packet_get_1_remote(int phone, size_t content);
    196 
    197 /** Releases the packet queue.
    198  *  All packets in the queue are marked as free for use.
    199  *  The packet queue may be one packet only.
    200  *  The module should not use the packets after this point until they are received or obtained again.
    201  *  @param[in] phone The packet server module phone.
    202  *  @param[in] packet_id The packet identifier.
    203  */
    204 extern void pq_release_remote(int phone, packet_id_t packet_id);
    205 
    206 /** Returns the packet copy.
    207  *  Copies the addresses, data, order and metric values.
    208  *  Does not copy the queue placement.
    209  *  @param[in] phone The packet server module phone.
    210  *  @param[in] packet The original packet.
    211  *  @returns The packet copy.
    212  *  @returns NULL on error.
    213  */
     101extern void *packet_prefix(packet_t, size_t);
     102extern void *packet_suffix(packet_t, size_t);
     103extern int packet_trim(packet_t, size_t, size_t);
     104extern int packet_copy_data(packet_t, const void *, size_t);
     105extern packet_id_t packet_get_id(const packet_t);
     106extern size_t packet_get_data_length(const packet_t);
     107extern void *packet_get_data(const packet_t);
     108extern int packet_get_addr(const packet_t, uint8_t **, uint8_t **);
     109extern int packet_set_addr(packet_t, const uint8_t *, const uint8_t *, size_t);
    214110extern packet_t packet_get_copy(int phone, packet_t packet);
    215111
Note: See TracChangeset for help on using the changeset viewer.