Subversion Repositories HelenOS

Rev

Rev 2831 | Rev 2844 | Go to most recent revision | Only display areas with differences | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 2831 Rev 2843
1
/*
1
/*
2
 * Copyright (c) 2008 Jakub Jermar
2
 * Copyright (c) 2008 Jakub Jermar
3
 * All rights reserved.
3
 * All rights reserved.
4
 *
4
 *
5
 * Redistribution and use in source and binary forms, with or without
5
 * Redistribution and use in source and binary forms, with or without
6
 * modification, are permitted provided that the following conditions
6
 * modification, are permitted provided that the following conditions
7
 * are met:
7
 * are met:
8
 *
8
 *
9
 * - Redistributions of source code must retain the above copyright
9
 * - Redistributions of source code must retain the above copyright
10
 *   notice, this list of conditions and the following disclaimer.
10
 *   notice, this list of conditions and the following disclaimer.
11
 * - Redistributions in binary form must reproduce the above copyright
11
 * - Redistributions in binary form must reproduce the above copyright
12
 *   notice, this list of conditions and the following disclaimer in the
12
 *   notice, this list of conditions and the following disclaimer in the
13
 *   documentation and/or other materials provided with the distribution.
13
 *   documentation and/or other materials provided with the distribution.
14
 * - The name of the author may not be used to endorse or promote products
14
 * - The name of the author may not be used to endorse or promote products
15
 *   derived from this software without specific prior written permission.
15
 *   derived from this software without specific prior written permission.
16
 *
16
 *
17
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27
 */
27
 */
28
 
28
 
29
/** @addtogroup fs
29
/** @addtogroup fs
30
 * @{
30
 * @{
31
 */
31
 */
32
 
32
 
33
/**
33
/**
34
 * @file    fat_ops.c
34
 * @file    fat_ops.c
35
 * @brief   Implementation of VFS operations for the FAT file system server.
35
 * @brief   Implementation of VFS operations for the FAT file system server.
36
 */
36
 */
37
 
37
 
38
#include "fat.h"
38
#include "fat.h"
39
#include "../../vfs/vfs.h"
39
#include "../../vfs/vfs.h"
40
#include <libfs.h>
40
#include <libfs.h>
41
#include <ipc/ipc.h>
41
#include <ipc/ipc.h>
42
#include <async.h>
42
#include <async.h>
43
#include <errno.h>
43
#include <errno.h>
44
#include <string.h>
44
#include <string.h>
45
#include <byteorder.h>
45
#include <byteorder.h>
46
#include <libadt/hash_table.h>
46
#include <libadt/hash_table.h>
47
#include <libadt/list.h>
47
#include <libadt/list.h>
48
#include <assert.h>
48
#include <assert.h>
49
 
49
 
-
 
50
#define BS_BLOCK        0
-
 
51
 
-
 
52
#define FIN_KEY_DEV_HANDLE  0
-
 
53
#define FIN_KEY_INDEX       1
-
 
54
 
50
/** Hash table of FAT in-core nodes. */
55
/** Hash table of FAT in-core nodes. */
51
hash_table_t fin_hash;
56
hash_table_t fin_hash;
52
 
57
 
53
/** List of free FAT in-core nodes. */
58
/** List of free FAT in-core nodes. */
54
link_t ffn_head;
59
link_t ffn_head;
55
 
60
 
56
#define FAT_NAME_LEN        8
61
#define FAT_NAME_LEN        8
57
#define FAT_EXT_LEN     3
62
#define FAT_EXT_LEN     3
58
 
63
 
59
#define FAT_PAD         ' ' 
64
#define FAT_PAD         ' ' 
60
 
65
 
61
#define FAT_DENTRY_UNUSED   0x00
66
#define FAT_DENTRY_UNUSED   0x00
62
#define FAT_DENTRY_E5_ESC   0x05
67
#define FAT_DENTRY_E5_ESC   0x05
63
#define FAT_DENTRY_DOT      0x2e
68
#define FAT_DENTRY_DOT      0x2e
64
#define FAT_DENTRY_ERASED   0xe5
69
#define FAT_DENTRY_ERASED   0xe5
65
 
70
 
66
static void dentry_name_canonify(fat_dentry_t *d, char *buf)
71
static void dentry_name_canonify(fat_dentry_t *d, char *buf)
67
{
72
{
68
    int i;
73
    int i;
69
 
74
 
70
    for (i = 0; i < FAT_NAME_LEN; i++) {
75
    for (i = 0; i < FAT_NAME_LEN; i++) {
71
        if (d->name[i] == FAT_PAD) {
76
        if (d->name[i] == FAT_PAD) {
72
            buf++;
77
            buf++;
73
            break;
78
            break;
74
        }
79
        }
75
        if (d->name[i] == FAT_DENTRY_E5_ESC)
80
        if (d->name[i] == FAT_DENTRY_E5_ESC)
76
            *buf++ = 0xe5;
81
            *buf++ = 0xe5;
77
        else
82
        else
78
            *buf++ = d->name[i];
83
            *buf++ = d->name[i];
79
    }
84
    }
80
    if (d->ext[0] != FAT_PAD)
85
    if (d->ext[0] != FAT_PAD)
81
        *buf++ = '.';
86
        *buf++ = '.';
82
    for (i = 0; i < FAT_EXT_LEN; i++) {
87
    for (i = 0; i < FAT_EXT_LEN; i++) {
83
        if (d->ext[i] == FAT_PAD) {
88
        if (d->ext[i] == FAT_PAD) {
84
            *buf = '\0';
89
            *buf = '\0';
85
            return;
90
            return;
86
        }
91
        }
87
        if (d->ext[i] == FAT_DENTRY_E5_ESC)
92
        if (d->ext[i] == FAT_DENTRY_E5_ESC)
88
            *buf++ = 0xe5;
93
            *buf++ = 0xe5;
89
        else
94
        else
90
            *buf++ = d->ext[i];
95
            *buf++ = d->ext[i];
91
    }
96
    }
92
}
97
}
93
 
98
 
94
/* TODO and also move somewhere else */
99
/* TODO and also move somewhere else */
95
typedef struct {
100
typedef struct {
96
    void *data;
101
    void *data;
97
} block_t;
102
} block_t;
98
 
103
 
99
static block_t *block_get(dev_handle_t dev_handle, off_t offset)
104
static block_t *block_get(dev_handle_t dev_handle, off_t offset)
100
{
105
{
101
    return NULL;    /* TODO */
106
    return NULL;    /* TODO */
102
}
107
}
103
 
108
 
104
static block_t *fat_block_get(dev_handle_t dev_handle, fs_index_t index,
109
static block_t *fat_block_get(dev_handle_t dev_handle, fs_index_t index,
105
    off_t offset) {
110
    off_t offset) {
106
    return NULL;    /* TODO */
111
    return NULL;    /* TODO */
107
}
112
}
108
 
113
 
109
static void block_put(block_t *block)
114
static void block_put(block_t *block)
110
{
115
{
111
    /* TODO */
116
    /* TODO */
112
}
117
}
113
 
118
 
114
static void fat_node_initialize(fat_node_t *node)
119
static void fat_node_initialize(fat_node_t *node)
115
{
120
{
116
    node->type = 0;
121
    node->type = 0;
117
    node->index = 0;
122
    node->index = 0;
118
    node->pindex = 0;
123
    node->pindex = 0;
119
    node->dev_handle = 0;
124
    node->dev_handle = 0;
120
    link_initialize(&node->fin_link);
125
    link_initialize(&node->fin_link);
121
    link_initialize(&node->ffn_link);
126
    link_initialize(&node->ffn_link);
122
    node->size = 0;
127
    node->size = 0;
123
    node->lnkcnt = 0;
128
    node->lnkcnt = 0;
124
    node->refcnt = 0;
129
    node->refcnt = 0;
125
    node->dirty = false;
130
    node->dirty = false;
126
}
131
}
127
 
132
 
-
 
133
static uint16_t fat_bps_get(dev_handle_t dev_handle)
-
 
134
{
-
 
135
    block_t *bb;
-
 
136
    uint16_t bps;
-
 
137
   
-
 
138
    bb = block_get(dev_handle, BS_BLOCK);
-
 
139
    assert(bb != NULL);
-
 
140
    bps = uint16_t_le2host(((fat_bs_t *)bb->data)->bps);
-
 
141
    block_put(bb);
-
 
142
 
-
 
143
    return bps;
-
 
144
}
-
 
145
 
128
static void fat_sync_node(fat_node_t *node)
146
static void fat_sync_node(fat_node_t *node)
129
{
147
{
130
    /* TODO */
148
    /* TODO */
131
}
149
}
132
 
150
 
-
 
151
/** Instantiate a FAT in-core node.
-
 
152
 *
-
 
153
 * FAT stores the info necessary for instantiation of a node in the parent of
-
 
154
 * that node.  This design necessitated the addition of the parent node index
-
 
155
 * parameter to this otherwise generic libfs API.
-
 
156
 */
133
static void *
157
static void *
134
fat_node_get(dev_handle_t dev_handle, fs_index_t index, fs_index_t pindex)
158
fat_node_get(dev_handle_t dev_handle, fs_index_t index, fs_index_t pindex)
135
{
159
{
136
    link_t *lnk;
160
    link_t *lnk;
137
    fat_node_t *node = NULL;
161
    fat_node_t *node = NULL;
138
    block_t *bb;
-
 
139
    block_t *b;
162
    block_t *b;
-
 
163
    unsigned bps;
-
 
164
    unsigned dps;
140
    fat_dentry_t *d;
165
    fat_dentry_t *d;
141
    unsigned bps;       /* bytes per sector */
166
    unsigned i, j;
142
    unsigned dps;       /* dentries per sector */
-
 
143
 
167
 
144
    unsigned long key[] = {
168
    unsigned long key[] = {
145
        dev_handle,
169
        [FIN_KEY_DEV_HANDLE] = dev_handle,
146
        index
170
        [FIN_KEY_INDEX] = index
147
    };
171
    };
148
 
172
 
149
    lnk = hash_table_find(&fin_hash, key);
173
    lnk = hash_table_find(&fin_hash, key);
150
    if (lnk) {
174
    if (lnk) {
151
        /*
175
        /*
152
         * The in-core node was found in the hash table.
176
         * The in-core node was found in the hash table.
153
         */
177
         */
154
        node = hash_table_get_instance(lnk, fat_node_t, fin_link);
178
        node = hash_table_get_instance(lnk, fat_node_t, fin_link);
155
        if (!node->refcnt++)
179
        if (!node->refcnt++)
156
            list_remove(&node->ffn_link);
180
            list_remove(&node->ffn_link);
157
        return (void *) node;  
181
        return (void *) node;  
158
    }
182
    }
159
 
183
 
-
 
184
    bps = fat_bps_get(dev_handle);
-
 
185
    dps = bps / sizeof(fat_dentry_t);
-
 
186
   
160
    if (!list_empty(&ffn_head)) {
187
    if (!list_empty(&ffn_head)) {
161
        /*
188
        /*
162
         * We are going to reuse a node from the free list.
189
         * We are going to reuse a node from the free list.
163
         */
190
         */
164
        lnk = ffn_head.next;
191
        lnk = ffn_head.next;
165
        list_remove(lnk);
192
        list_remove(lnk);
166
        node = list_get_instance(lnk, fat_node_t, ffn_link);
193
        node = list_get_instance(lnk, fat_node_t, ffn_link);
167
        assert(!node->refcnt);
194
        assert(!node->refcnt);
168
        if (node->dirty)
195
        if (node->dirty)
169
            fat_sync_node(node);
196
            fat_sync_node(node);
-
 
197
        key[FIN_KEY_DEV_HANDLE] = node->dev_handle;
-
 
198
        key[FIN_KEY_INDEX] = node->index;
-
 
199
        hash_table_remove(&fin_hash, key, sizeof(key)/sizeof(*key));
170
    } else {
200
    } else {
171
        /*
201
        /*
172
         * We need to allocate a new node.
202
         * We need to allocate a new node.
173
         */
203
         */
174
        node = malloc(sizeof(fat_node_t));
204
        node = malloc(sizeof(fat_node_t));
175
        if (!node)
205
        if (!node)
176
            return NULL;
206
            return NULL;
177
    }
207
    }
178
    fat_node_initialize(node);
208
    fat_node_initialize(node);
-
 
209
    node->refcnt++;
-
 
210
    node->lnkcnt++;
-
 
211
    node->dev_handle = dev_handle;
-
 
212
    node->index = index;
-
 
213
    node->pindex = pindex;
179
 
214
 
-
 
215
    /*
-
 
216
     * Because of the design of the FAT file system, we have no clue about
-
 
217
     * how big (i.e. how many directory entries it contains) is the parent
-
 
218
     * of the node we are trying to instantiate.  However, we know that it
-
 
219
     * must contain a directory entry for our node of interest.  We simply
-
 
220
     * scan the parent until we find it.
-
 
221
     */
-
 
222
    for (i = 0; ; i++) {
-
 
223
        b = fat_block_get(node->dev_handle, node->pindex, i);
180
    if (!pindex) {
224
        if (!b) {
-
 
225
            node->refcnt--;
-
 
226
            list_append(&node->ffn_link, &ffn_head);
-
 
227
            return NULL;
181
       
228
        }
-
 
229
        for (j = 0; j < dps; j++) {
-
 
230
            d = ((fat_dentry_t *)b->data) + j;
-
 
231
            if (d->firstc == node->index)
182
    } else {
232
                goto found;
-
 
233
        }
-
 
234
        block_put(b);
183
    }
235
    }
-
 
236
   
-
 
237
found:
-
 
238
    if (!(d->attr & (FAT_ATTR_SUBDIR | FAT_ATTR_VOLLABEL)))
-
 
239
        node->type = FAT_FILE;
-
 
240
    if ((d->attr & FAT_ATTR_SUBDIR) || !pindex)
-
 
241
        node->type = FAT_DIRECTORY;
-
 
242
    assert((node->type == FAT_FILE) || (node->type == FAT_DIRECTORY));
-
 
243
   
-
 
244
    node->size = uint32_t_le2host(d->size);
-
 
245
    block_put(b);
-
 
246
   
-
 
247
    key[FIN_KEY_DEV_HANDLE] = node->dev_handle;
-
 
248
    key[FIN_KEY_INDEX] = node->index;
-
 
249
    hash_table_insert(&fin_hash, key, &node->fin_link);
184
 
250
 
-
 
251
    return node;
185
}
252
}
186
 
253
 
187
#define BS_BLOCK    0
-
 
188
 
-
 
189
static void *fat_match(void *prnt, const char *component)
254
static void *fat_match(void *prnt, const char *component)
190
{
255
{
191
    fat_node_t *parentp = (fat_node_t *)prnt;
256
    fat_node_t *parentp = (fat_node_t *)prnt;
192
    char name[FAT_NAME_LEN + 1 + FAT_EXT_LEN + 1];
257
    char name[FAT_NAME_LEN + 1 + FAT_EXT_LEN + 1];
193
    unsigned i, j;
258
    unsigned i, j;
194
    unsigned bps;       /* bytes per sector */
259
    unsigned bps;       /* bytes per sector */
195
    unsigned dps;       /* dentries per sector */
260
    unsigned dps;       /* dentries per sector */
196
    unsigned blocks;
261
    unsigned blocks;
197
    fat_dentry_t *d;
262
    fat_dentry_t *d;
198
    block_t *bb;
-
 
199
    block_t *b;
263
    block_t *b;
200
 
264
 
201
    bb = block_get(parentp->dev_handle, BS_BLOCK);
265
    bps = fat_bps_get(parentp->dev_handle);
202
    if (!bb)
-
 
203
        return NULL;
-
 
204
    bps = uint16_t_le2host(((fat_bs_t *)bb->data)->bps);
-
 
205
    block_put(bb);
-
 
206
    dps = bps / sizeof(fat_dentry_t);
266
    dps = bps / sizeof(fat_dentry_t);
207
    blocks = parentp->size / bps + (parentp->size % bps != 0);
267
    blocks = parentp->size / bps + (parentp->size % bps != 0);
208
    for (i = 0; i < blocks; i++) {
268
    for (i = 0; i < blocks; i++) {
209
        unsigned dentries;
269
        unsigned dentries;
210
       
270
       
211
        b = fat_block_get(parentp->dev_handle, parentp->index, i);
271
        b = fat_block_get(parentp->dev_handle, parentp->index, i);
212
        if (!b)
272
        if (!b)
213
            return NULL;
273
            return NULL;
214
 
274
 
215
        dentries = (i == blocks - 1) ?
275
        dentries = (i == blocks - 1) ?
216
            parentp->size % sizeof(fat_dentry_t) :
276
            parentp->size % sizeof(fat_dentry_t) :
217
            dps;
277
            dps;
218
        for (j = 0; j < dentries; j++) {
278
        for (j = 0; j < dentries; j++) {
219
            d = ((fat_dentry_t *)b->data) + j;
279
            d = ((fat_dentry_t *)b->data) + j;
220
            if (d->attr & FAT_ATTR_VOLLABEL) {
280
            if (d->attr & FAT_ATTR_VOLLABEL) {
221
                /* volume label entry */
281
                /* volume label entry */
222
                continue;
282
                continue;
223
            }
283
            }
224
            if (d->name[0] == FAT_DENTRY_ERASED) {
284
            if (d->name[0] == FAT_DENTRY_ERASED) {
225
                /* not-currently-used entry */
285
                /* not-currently-used entry */
226
                continue;
286
                continue;
227
            }
287
            }
228
            if (d->name[0] == FAT_DENTRY_UNUSED) {
288
            if (d->name[0] == FAT_DENTRY_UNUSED) {
229
                /* never used entry */
289
                /* never used entry */
230
                block_put(b);
290
                block_put(b);
231
                return NULL;
291
                return NULL;
232
            }
292
            }
233
            if (d->name[0] == FAT_DENTRY_DOT) {
293
            if (d->name[0] == FAT_DENTRY_DOT) {
234
                /*
294
                /*
235
                 * Most likely '.' or '..'.
295
                 * Most likely '.' or '..'.
236
                 * It cannot occur in a regular file name.
296
                 * It cannot occur in a regular file name.
237
                 */
297
                 */
238
                continue;
298
                continue;
239
            }
299
            }
240
       
300
       
241
            dentry_name_canonify(d, name);
301
            dentry_name_canonify(d, name);
242
            if (strcmp(name, component) == 0) {
302
            if (strcmp(name, component) == 0) {
243
                /* hit */
303
                /* hit */
244
                void *node = fat_node_get(parentp->dev_handle,
304
                void *node = fat_node_get(parentp->dev_handle,
245
                    (fs_index_t)uint16_t_le2host(d->firstc),
305
                    (fs_index_t)uint16_t_le2host(d->firstc),
246
                    parentp->index);
306
                    parentp->index);
247
                block_put(b);
307
                block_put(b);
248
                return node;
308
                return node;
249
            }
309
            }
250
        }
310
        }
251
        block_put(b);
311
        block_put(b);
252
    }
312
    }
253
 
313
 
254
    return NULL;
314
    return NULL;
255
}
315
}
256
 
316
 
257
static fs_index_t fat_index_get(void *node)
317
static fs_index_t fat_index_get(void *node)
258
{
318
{
259
    fat_node_t *fnodep = (fat_node_t *)node;
319
    fat_node_t *fnodep = (fat_node_t *)node;
260
    if (!fnodep)
320
    if (!fnodep)
261
        return 0;
321
        return 0;
262
    return fnodep->index;
322
    return fnodep->index;
263
}
323
}
264
 
324
 
265
static size_t fat_size_get(void *node)
325
static size_t fat_size_get(void *node)
266
{
326
{
267
    return ((fat_node_t *)node)->size;
327
    return ((fat_node_t *)node)->size;
268
}
328
}
269
 
329
 
270
static unsigned fat_lnkcnt_get(void *node)
330
static unsigned fat_lnkcnt_get(void *node)
271
{
331
{
272
    return ((fat_node_t *)node)->lnkcnt;
332
    return ((fat_node_t *)node)->lnkcnt;
273
}
333
}
274
 
334
 
275
static bool fat_is_directory(void *node)
335
static bool fat_is_directory(void *node)
276
{
336
{
277
    return ((fat_node_t *)node)->type == FAT_DIRECTORY;
337
    return ((fat_node_t *)node)->type == FAT_DIRECTORY;
278
}
338
}
279
 
339
 
280
static bool fat_is_file(void *node)
340
static bool fat_is_file(void *node)
281
{
341
{
282
    return ((fat_node_t *)node)->type == FAT_FILE;
342
    return ((fat_node_t *)node)->type == FAT_FILE;
283
}
343
}
284
 
344
 
285
/** libfs operations */
345
/** libfs operations */
286
libfs_ops_t fat_libfs_ops = {
346
libfs_ops_t fat_libfs_ops = {
287
    .match = fat_match,
347
    .match = fat_match,
288
    .node_get = fat_node_get,
348
    .node_get = fat_node_get,
289
    .create = NULL,
349
    .create = NULL,
290
    .destroy = NULL,
350
    .destroy = NULL,
291
    .link = NULL,
351
    .link = NULL,
292
    .unlink = NULL,
352
    .unlink = NULL,
293
    .index_get = fat_index_get,
353
    .index_get = fat_index_get,
294
    .size_get = fat_size_get,
354
    .size_get = fat_size_get,
295
    .lnkcnt_get = fat_lnkcnt_get,
355
    .lnkcnt_get = fat_lnkcnt_get,
296
    .has_children = NULL,
356
    .has_children = NULL,
297
    .root_get = NULL,
357
    .root_get = NULL,
298
    .plb_get_char = NULL,
358
    .plb_get_char = NULL,
299
    .is_directory = fat_is_directory,
359
    .is_directory = fat_is_directory,
300
    .is_file = fat_is_file
360
    .is_file = fat_is_file
301
};
361
};
302
 
362
 
303
void fat_lookup(ipc_callid_t rid, ipc_call_t *request)
363
void fat_lookup(ipc_callid_t rid, ipc_call_t *request)
304
{
364
{
305
    libfs_lookup(&fat_libfs_ops, fat_reg.fs_handle, rid, request);
365
    libfs_lookup(&fat_libfs_ops, fat_reg.fs_handle, rid, request);
306
}
366
}
307
 
367
 
308
/**
368
/**
309
 * @}
369
 * @}
310
 */
370
 */
311
 
371