Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

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

    rb69ceea rc69d327  
    2727 */
    2828
    29 /** @addtogroup libnet
     29/** @addtogroup packet
    3030 *  @{
    3131 */
    3232
    3333/** @file
    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
    45  */
    46 
    47 #ifndef LIBNET_PACKET_CLIENT_H_
    48 #define LIBNET_PACKET_CLIENT_H_
     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 - by passing the packets to the next module and stopping using the passed ones.
     41 *  @see packet.h
     42 */
     43
     44#ifndef __NET_PACKET_CLIENT_H__
     45#define __NET_PACKET_CLIENT_H__
    4946
    5047#include <net/packet.h>
    5148
    52 /** @name Packet client interface */
     49/** @name Packet client interface
     50 */
    5351/*@{*/
    5452
    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.
    66  */
    67 #define PACKET_PREFIX(packet, type) \
    68         (type *) packet_prefix((packet), sizeof(type))
    69 
    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.
    81  */
    82 #define PACKET_SUFFIX(packet, type) \
    83         (type *) packet_suffix((packet), sizeof(type))
     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.
     60 */
     61#define PACKET_PREFIX(packet, type)     (type *) packet_prefix((packet), sizeof(type))
     62
     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 */
     71#define PACKET_SUFFIX(packet, type)     (type *) packet_suffix((packet), sizeof(type))
    8472
    8573/** Trims the actual packet content by the specified prefix and suffix types.
    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.
    97  */
    98 #define PACKET_TRIM(packet, prefix, suffix) \
    99         packet_trim((packet), sizeof(prefix), sizeof(suffix))
    100 
    101 extern void *packet_prefix(packet_t, size_t);
    102 extern void *packet_suffix(packet_t, size_t);
    103 extern int packet_trim(packet_t, size_t, size_t);
    104 extern int packet_copy_data(packet_t, const void *, size_t);
    105 extern packet_id_t packet_get_id(const packet_t);
    106 extern size_t packet_get_data_length(const packet_t);
    107 extern void *packet_get_data(const packet_t);
    108 extern int packet_get_addr(const packet_t, uint8_t **, uint8_t **);
    109 extern int packet_set_addr(packet_t, const uint8_t *, const uint8_t *, size_t);
     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.
     81 */
     82#define PACKET_TRIM(packet, prefix, suffix)     packet_trim((packet), sizeof(prefix), sizeof(suffix))
     83
     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 */
     90extern 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 */
     98extern 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 */
     108extern 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 */
     119extern 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 */
     126extern 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 */
     133extern 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 */
     140extern 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 */
     150extern 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 */
     161extern 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 */
     174extern 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 */
     186extern 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 */
     195extern 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 */
     204extern 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 */
    110214extern packet_t packet_get_copy(int phone, packet_t packet);
    111215
Note: See TracChangeset for help on using the changeset viewer.