Subversion Repositories HelenOS

Rev

Rev 4731 | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 4731 Rev 4756
Line 50... Line 50...
50 
 */
 50 
 */
51 
/*@{*/
 51 
/*@{*/
52 
 
 52 
 
53 
/** Allocates the specified type right before the actual packet content and returns its pointer.
 53 
/** Allocates the specified type right before the actual packet content and returns its pointer.
54 
 *  The wrapper of the packet_prepend() function.
 54 
 *  The wrapper of the packet_prepend() function.
55 
 *  @param packet The packet to be used. Input parameter.
 55 
 *  @param[in] packet The packet to be used.
56 
 *  @param type The type to be allocated at the beginning of the packet content. Input parameter.
 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.
 57 
 *  @returns The typed pointer to the allocated memory.
58 
 *  @returns NULL if the packet is not valid.
 58 
 *  @returns NULL if the packet is not valid.
59 
 *  @returns NULL if there is not enough memory left.
 59 
 *  @returns NULL if there is not enough memory left.
60 
 */
 60 
 */
61 
#define PACKET_PREFIX( packet, type )   ( type * ) packet_prefix(( packet ), sizeof( type ))
 61 
#define PACKET_PREFIX( packet, type )   ( type * ) packet_prefix(( packet ), sizeof( type ))
62 
 
 62 
 
63 
/** Allocates the specified type right after the actual packet content and returns its pointer.
 63 
/** Allocates the specified type right after the actual packet content and returns its pointer.
64 
 *  The wrapper of the packet_append() function.
 64 
 *  The wrapper of the packet_append() function.
65 
 *  @param packet The packet to be used. Input parameter.
 65 
 *  @param[in] packet The packet to be used.
66 
 *  @param type The type to be allocated at the end of the packet content. Input parameter.
 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.
 67 
 *  @returns The typed pointer to the allocated memory.
68 
 *  @returns NULL if the packet is not valid.
 68 
 *  @returns NULL if the packet is not valid.
69 
 *  @returns NULL if there is not enough memory left.
 69 
 *  @returns NULL if there is not enough memory left.
70 
 */
 70 
 */
71 
#define PACKET_SUFFIX( packet, type )   ( type * ) packet_suffix(( packet ), sizeof( type ))
 71 
#define PACKET_SUFFIX( packet, type )   ( type * ) packet_suffix(( packet ), sizeof( type ))
72 
 
 72 
 
73 
/** Trims the actual packet content by the specified prefix and suffix types.
 73 
/** Trims the actual packet content by the specified prefix and suffix types.
74 
 *  The wrapper of the packet_trim() function.
 74 
 *  The wrapper of the packet_trim() function.
75 
 *  @param packet The packet to be trimmed. Input parameter.
 75 
 *  @param[in] packet The packet to be trimmed.
76 
 *  @param prefix The type of the prefix to be removed from the beginning of the packet content. Input parameter.
 76 
 *  @param[in] prefix The type of the prefix to be removed from the beginning of the packet content.
77 
 *  @param suffix The type of the suffix to be removed from the end of the packet content. Input parameter.
 77 
 *  @param[in] suffix The type of the suffix to be removed from the end of the packet content.
78 
 *  @returns EOK on success.
 78 
 *  @returns EOK on success.
79 
 *  @returns EINVAL if the packet is not valid.
 79 
 *  @returns EINVAL if the packet is not valid.
80 
 *  @returns ENOMEM if there is not enough memory left.
 80 
 *  @returns ENOMEM if there is not enough memory left.
81 
 */
 81 
 */
82 
#define PACKET_TRIM( packet, prefix, suffix )   packet_trim(( packet ), sizeof( prefix ), sizeof( suffix ))
 82 
#define PACKET_TRIM( packet, prefix, suffix )   packet_trim(( packet ), sizeof( prefix ), sizeof( suffix ))
83 
 
 83 
 
84 
/** Allocates the specified space right before the actual packet content and returns its pointer.
 84 
/** Allocates the specified space right before the actual packet content and returns its pointer.
85 
 *  @param packet The packet to be used. Input parameter.
 85 
 *  @param[in] packet The packet to be used.
86 
 *  @param length The space length to be allocated at the beginning of the packet content. Input parameter.
 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.
 87 
 *  @returns The pointer to the allocated memory.
88 
 *  @returns NULL if there is not enough memory left.
 88 
 *  @returns NULL if there is not enough memory left.
89 
 */
 89 
 */
90 
void *  packet_prefix( packet_t packet, size_t length );
 90 
void *  packet_prefix( packet_t packet, size_t length );
91 
 
 91 
 
92 
/** Allocates the specified space right after the actual packet content and returns its pointer.
 92 
/** Allocates the specified space right after the actual packet content and returns its pointer.
93 
 *  @param packet The packet to be used. Input parameter.
 93 
 *  @param[in] packet The packet to be used.
94 
 *  @param length The space length to be allocated at the end of the packet content. Input parameter.
 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.
 95 
 *  @returns The pointer to the allocated memory.
96 
 *  @returns NULL if there is not enough memory left.
 96 
 *  @returns NULL if there is not enough memory left.
97 
 */
 97 
 */
98 
void *  packet_suffix( packet_t packet, size_t length );
 98 
void *  packet_suffix( packet_t packet, size_t length );
99 
 
 99 
 
100 
/** Trims the actual packet content by the specified prefix and suffix lengths.
 100 
/** Trims the actual packet content by the specified prefix and suffix lengths.
101 
 *  @param packet The packet to be trimmed. Input parameter.
 101 
 *  @param[in] packet The packet to be trimmed.
102 
 *  @param prefix The prefix length to be removed from the beginning of the packet content. Input parameter.
 102 
 *  @param[in] prefix The prefix length to be removed from the beginning of the packet content.
103 
 *  @param suffix The suffix length to be removed from the end of the packet content. Input parameter.
 103 
 *  @param[in] suffix The suffix length to be removed from the end of the packet content.
104 
 *  @returns EOK on success.
 104 
 *  @returns EOK on success.
105 
 *  @returns EINVAL if the packet is not valid.
 105 
 *  @returns EINVAL if the packet is not valid.
106 
 *  @returns ENOMEM if there is not enough memory left.
 106 
 *  @returns ENOMEM if there is not enough memory left.
107 
 */
 107 
 */
108 
int packet_trim( packet_t packet, size_t prefix, size_t suffix );
 108 
int packet_trim( packet_t packet, size_t prefix, size_t suffix );
109 
 
 109 
 
110 
/** Copies the specified data to the beginning of the actual packet content.
 110 
/** Copies the specified data to the beginning of the actual packet content.
111 
 *  Pushes the content end if needed.
 111 
 *  Pushes the content end if needed.
112 
 *  @param packet The packet to be filled. Input parameter.
 112 
 *  @param[in] packet The packet to be filled.
113 
 *  @param data The data to be copied. Input parameter.
 113 
 *  @param[in] data The data to be copied.
114 
 *  @param length The length of the copied data. Input parameter.
 114 
 *  @param[in] length The length of the copied data.
115 
 *  @returns EOK on success.
 115 
 *  @returns EOK on success.
116 
 *  @returns EINVAL if the packet is not valid.
 116 
 *  @returns EINVAL if the packet is not valid.
117 
 *  @returns ENOMEM if there is not enough memory left.
 117 
 *  @returns ENOMEM if there is not enough memory left.
118 
 */
 118 
 */
119 
int packet_copy_data( packet_t packet, const void * data, size_t length );
 119 
int packet_copy_data( packet_t packet, const void * data, size_t length );
120 
 
 120 
 
121 
/** Returns the packet identifier.
 121 
/** Returns the packet identifier.
122 
 *  @param packet The packet. Input parameter.
 122 
 *  @param[in] packet The packet.
123 
 *  @returns The packet identifier.
 123 
 *  @returns The packet identifier.
124 
 *  @returns Zero (0) if the packet is not valid.
 124 
 *  @returns Zero (0) if the packet is not valid.
125 
 */
 125 
 */
126 
packet_id_t packet_get_id( const packet_t packet );
 126 
packet_id_t packet_get_id( const packet_t packet );
127 
 
 127 
 
128 
/** Returns the packet content length.
 128 
/** Returns the packet content length.
129 
 *  @param packet The packet. Input parameter.
 129 
 *  @param[in] packet The packet.
130 
 *  @returns The packet content length in bytes.
 130 
 *  @returns The packet content length in bytes.
131 
 *  @returns Zero (0) if the packet is not valid.
 131 
 *  @returns Zero (0) if the packet is not valid.
132 
 */
 132 
 */
133 
size_t  packet_get_data_length( const packet_t packet );
 133 
size_t  packet_get_data_length( const packet_t packet );
134 
 
 134 
 
135 
/** Returns the pointer to the beginning of the packet content.
 135 
/** Returns the pointer to the beginning of the packet content.
136 
 *  @param packet The packet. Input parameter.
 136 
 *  @param[in] packet The packet.
137 
 *  @returns The pointer to the beginning of the packet content.
 137 
 *  @returns The pointer to the beginning of the packet content.
138 
 *  @returns NULL if the packet is not valid.
 138 
 *  @returns NULL if the packet is not valid.
139 
 */
 139 
 */
140 
void *  packet_get_data( const packet_t packet );
 140 
void *  packet_get_data( const packet_t packet );
141 
 
 141 
 
142 
/** Returns the stored packet addresses and their length.
 142 
/** Returns the stored packet addresses and their length.
143 
 *  @param packet The packet. Input parameter.
 143 
 *  @param[in] packet The packet.
144 
 *  @param src The source address. May be NULL if not desired. Output parameter.
 144 
 *  @param[out] src The source address. May be NULL if not desired.
145 
 *  @param dest The destination address. May be NULL if not desired. Output parameter.
 145 
 *  @param[out] dest The destination address. May be NULL if not desired.
146 
 *  @returns The stored addresses length.
 146 
 *  @returns The stored addresses length.
147 
 *  @returns Zero (0) if the addresses are not present.
 147 
 *  @returns Zero (0) if the addresses are not present.
148 
 *  @returns EINVAL if the packet is not valid.
 148 
 *  @returns EINVAL if the packet is not valid.
149 
 */
 149 
 */
150 
int packet_get_addr( const packet_t packet, uint8_t ** src, uint8_t ** dest );
 150 
int packet_get_addr( const packet_t packet, uint8_t ** src, uint8_t ** dest );
151 
 
 151 
 
152 
/** Sets the packet addresses.
 152 
/** Sets the packet addresses.
153 
 *  @param packet The packet. Input parameter.
 153 
 *  @param[in] packet The packet.
154 
 *  @param src The new source address. May be NULL. Input parameter.
 154 
 *  @param[in] src The new source address. May be NULL.
155 
 *  @param dest The new destination address. May be NULL. Input parameter.
 155 
 *  @param[in] dest The new destination address. May be NULL.
156 
 *  @param addr_len The addresses length.
 156 
 *  @param[in] addr_len The addresses length.
157 
 *  @returns EOK on success.
 157 
 *  @returns EOK on success.
158 
 *  @returns EINVAL if the packet is not valid.
 158 
 *  @returns EINVAL if the packet is not valid.
159 
 *  @returns ENOMEM if there is not enough memory left.
 159 
 *  @returns ENOMEM if there is not enough memory left.
160 
 */
 160 
 */
161 
int packet_set_addr( packet_t packet, const uint8_t * src, const uint8_t * dest, size_t addr_len );
 161 
int packet_set_addr( packet_t packet, const uint8_t * src, const uint8_t * dest, size_t addr_len );
162 
 
 162 
 
163 
/** Translates the packet identifier to the packet reference.
 163 
/** Translates the packet identifier to the packet reference.
164 
 *  Tries to find mapping first.
 164 
 *  Tries to find mapping first.
165 
 *  Contacts the packet server to share the packet if the mapping is not present.
 165 
 *  Contacts the packet server to share the packet if the mapping is not present.
166 
 *  @param phone The packet server module phone. Input parameter.
 166 
 *  @param[in] phone The packet server module phone.
167 
 *  @param packet The packet reference. Output parameter.
 167 
 *  @param[out] packet The packet reference.
168 
 *  @param packet_id The packet identifier. Input parameter.
 168 
 *  @param[in] packet_id The packet identifier.
169 
 *  @returns EOK on success.
 169 
 *  @returns EOK on success.
170 
 *  @returns EINVAL if the packet parameter is NULL.
 170 
 *  @returns EINVAL if the packet parameter is NULL.
171 
 *  @returns Other error codes as defined for the NET_PACKET_GET_SIZE message.
 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.
 172 
 *  @returns Other error codes as defined for the packet_return() function.
173 
 */
 173 
 */
174 
int packet_translate( int phone, packet_ref packet, packet_id_t packet_id );
 174 
int packet_translate( int phone, packet_ref packet, packet_id_t packet_id );
175 
 
 175 
 
176 
/** Obtains the packet of the given dimensions.
 176 
/** Obtains the packet of the given dimensions.
177 
 *  Contacts the packet server to return the appropriate packet.
 177 
 *  Contacts the packet server to return the appropriate packet.
178 
 *  @param phone The packet server module phone. Input parameter.
 178 
 *  @param[in] phone The packet server module phone.
179 
 *  @param addr_len The source and destination addresses maximal length in bytes. Input parameter.
 179 
 *  @param[in] addr_len The source and destination addresses maximal length in bytes.
180 
 *  @param max_prefix The maximal prefix length in bytes. Input parameter.
 180 
 *  @param[in] max_prefix The maximal prefix length in bytes.
181 
 *  @param max_content The maximal content length in bytes. Input parameter.
 181 
 *  @param[in] max_content The maximal content length in bytes.
182 
 *  @param max_suffix The maximal suffix length in bytes. Input parameter.
 182 
 *  @param[in] max_suffix The maximal suffix length in bytes.
183 
 *  @returns The packet reference.
 183 
 *  @returns The packet reference.
184 
 *  @returns NULL on error.
 184 
 *  @returns NULL on error.
185 
 */
 185 
 */
186 
packet_t packet_get_4( int phone, size_t max_content, size_t addr_len, size_t max_prefix, size_t max_suffix );
 186 
packet_t packet_get_4( int phone, size_t max_content, size_t addr_len, size_t max_prefix, size_t max_suffix );
187 
 
 187 
 
188 
/** Obtains the packet of the given content size.
 188 
/** Obtains the packet of the given content size.
189 
 *  Contacts the packet server to return the appropriate packet.
 189 
 *  Contacts the packet server to return the appropriate packet.
190 
 *  @param phone The packet server module phone. Input parameter.
 190 
 *  @param[in] phone The packet server module phone.
191 
 *  @param content The maximal content length in bytes. Input parameter.
 191 
 *  @param[in] content The maximal content length in bytes.
192 
 *  @returns The packet reference.
 192 
 *  @returns The packet reference.
193 
 *  @returns NULL on error.
 193 
 *  @returns NULL on error.
194 
 */
 194 
 */
195 
packet_t packet_get_1( int phone, size_t content );
 195 
packet_t packet_get_1( int phone, size_t content );
196 
 
 196 
 
197 
/** Releases the packet queue.
 197 
/** Releases the packet queue.
198 
 *  All packets in the queue are marked as free for use.
 198 
 *  All packets in the queue are marked as free for use.
199 
 *  The packet queue may be one packet only.
 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.
 200 
 *  The module should not use the packets after this point until they are received or obtained again.
201 
 *  @param phone The packet server module phone. Input parameter.
 201 
 *  @param[in] phone The packet server module phone.
202 
 *  @param packet_id The packet identifier. Input parameter.
 202 
 *  @param[in] packet_id The packet identifier.
203 
 */
 203 
 */
204 
void pq_release( int phone, packet_id_t packet_id );
 204 
void pq_release( int phone, packet_id_t packet_id );
205 
 
 205 
 
206 
/** \todo
 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.
207 
 */
 213 
 */
208 
packet_t    packet_get_copy( int phone, packet_t packet );
 214 
packet_t    packet_get_copy( int phone, packet_t packet );
209 
 
 215 
 
210 
/*@}*/
 216 
/*@}*/
211 
 
 217