Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Examples

cfs.h

Go to the documentation of this file.
00001 /**
00002  * \addtogroup sys
00003  * @{
00004  */
00005 
00006 /**
00007  * \defgroup cfs The Contiki file system interface
00008  *
00009  * The Contiki file system interface (CFS) defines an abstract API for
00010  * reading directories and for reading and writing files. The CFS API
00011  * is intentionally simple. The CFS API is modeled after the POSIX
00012  * file API, and slightly simplified.
00013  *
00014  * @{
00015  */
00016 
00017 /**
00018  * \file
00019  *         CFS header file.
00020  * \author
00021  *         Adam Dunkels <adam@sics.se>
00022  *
00023  */
00024 
00025 /*
00026  * Copyright (c) 2004, Swedish Institute of Computer Science.
00027  * All rights reserved.
00028  *
00029  * Redistribution and use in source and binary forms, with or without
00030  * modification, are permitted provided that the following conditions
00031  * are met:
00032  * 1. Redistributions of source code must retain the above copyright
00033  *    notice, this list of conditions and the following disclaimer.
00034  * 2. Redistributions in binary form must reproduce the above copyright
00035  *    notice, this list of conditions and the following disclaimer in the
00036  *    documentation and/or other materials provided with the distribution.
00037  * 3. Neither the name of the Institute nor the names of its contributors
00038  *    may be used to endorse or promote products derived from this software
00039  *    without specific prior written permission.
00040  *
00041  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00042  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00043  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00044  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00045  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00046  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00047  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00048  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00049  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00050  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00051  * SUCH DAMAGE.
00052  *
00053  * This file is part of the Contiki operating system.
00054  *
00055  * Author: Adam Dunkels <adam@sics.se>
00056  *
00057  * $Id: cfs.h,v 1.1 2006/06/17 22:41:15 adamdunkels Exp $
00058  */
00059 #ifndef __CFS_H__
00060 #define __CFS_H__
00061 
00062 #include "cfs/cfs-service.h"
00063 
00064 /**
00065  * Specify that cfs_open() should open a file for reading.
00066  *
00067  * This constant indicates to cfs_open() that a file should be opened
00068  * for reading. CFS_WRITE should be used if the file is opened for
00069  * writing, and CFS_READ + CFS_WRITE indicates that the file is opened
00070  * for both reading and writing.
00071  *
00072  * \sa cfs_open()
00073  */
00074 #define CFS_READ  0
00075 
00076 /**
00077  * Specify that cfs_open() should open a file for writing.
00078  *
00079  * This constant indicates to cfs_open() that a file should be opened
00080  * for writing. CFS_READ should be used if the file is opened for
00081  * reading, and CFS_READ + CFS_WRITE indicates that the file is opened
00082  * for both reading and writing.
00083  *
00084  * \sa cfs_open()
00085  */
00086 #define CFS_WRITE 1
00087 
00088 /**
00089  * \brief      Open a file.
00090  * \param name The name of the file.
00091  * \param flags CFS_READ, or CFS_WRITE, or both.
00092  * \return     A file descriptor, if the file could be opened, or -1 if
00093  *             the file could not be opened.
00094  *
00095  *             This function opens a file and returns a file
00096  *             descriptor for the opened file. If the file could not
00097  *             be opened, the function returns -1. The function can
00098  *             open a file for reading or writing, or both.
00099  *
00100  *             An opened file must be closed with cfs_close().
00101  *
00102  * \sa         CFS_READ
00103  * \sa         CFS_WRITE
00104  * \sa         cfs_close()
00105  */
00106 int cfs_open(const char *name, int flags);
00107 
00108 /**
00109  * \brief      Close an open file.
00110  * \param fd   The file descriptor of the open file.
00111  *
00112  *             This function closes a file that has previously been
00113  *             opened with cfs_open().
00114  */
00115 void cfs_close(int fd);
00116 
00117 /**
00118  * \brief      Read data from an open file.
00119  * \param fd   The file descriptor of the open file.
00120  * \param buf  The buffer in which data should be read from the file.
00121  * \param len  The number of bytes that should be read.
00122  * \return     The number of bytes that was actually read from the file.
00123  *
00124  *             This function reads data from an open file into a
00125  *             buffer. The file must have first been opened with
00126  *             cfs_open() and the CFS_READ flag.
00127  */
00128 int cfs_read(int fd, char *buf, unsigned int len);
00129 
00130 /**
00131  * \brief      Write data to an open file.
00132  * \param fd   The file descriptor of the open file.
00133  * \param buf  The buffer from which data should be written to the file.
00134  * \param len  The number of bytes that should be written.
00135  * \return     The number of bytes that was actually written to the file.
00136  *
00137  *             This function reads writes data from a memory buffer to
00138  *             an open file. The file must have been opened with
00139  *             cfs_open() and the CFS_WRITE flag.
00140  */
00141 int cfs_write(int fd, char *buf, unsigned int len);
00142 
00143 /**
00144  * \brief      Seek to a specified position in an open file.
00145  * \param fd   The file descriptor of the open file.
00146  * \param offset The position in the file.
00147  * \return     The new position in the file.
00148  *
00149  *             This function moves the file position to the specified
00150  *             position in the file. The next byte that is read from
00151  *             or written to the file will be at the position given by
00152  *             the offset parameter.
00153  */
00154 int cfs_seek(int fd, unsigned int offset);
00155 
00156 /**
00157  * \brief      Open a directory for reading directory entries.
00158  * \param dirp A pointer to a struct cfs_dir that is filled in by the function.
00159  * \param name The name of the directory.
00160  * \return     0 or -1 if the directory could not be opened.
00161  *
00162  * \sa         cfs_readdir()
00163  * \sa         cfs_closedir()
00164  */
00165 int cfs_opendir(struct cfs_dir *dirp, const char *name);
00166 
00167 /**
00168  * \brief      Read a directory entry
00169  * \param dirp A pointer to a struct cfs_dir that has been opened with cfs_opendir().
00170  * \param dirent A pointer to a struct cfs_dirent that is filled in by cfs_readdir()
00171  * \retval 0   If a directory entry was read.
00172  * \retval 0   If no more directory entries can be read.
00173  *
00174  * \sa         cfs_opendir()
00175  * \sa         cfs_closedir()
00176  */
00177 int cfs_readdir(struct cfs_dir *dirp, struct cfs_dirent *dirent);
00178 
00179 /**
00180  * \brief      Close a directory opened with cfs_opendir().
00181  * \param dirp A pointer to a struct cfs_dir that has been opened with cfs_opendir().
00182  *
00183  * \sa         cfs_opendir()
00184  * \sa         cfs_readdir()
00185  */
00186 int cfs_closedir(struct cfs_dir *dirp);
00187 
00188 struct cfs_service_interface *cfs_find_service(void);
00189 
00190 #define cfs_open(name, flags)   (cfs_find_service()->open(name, flags))
00191 #define cfs_close(fd)           (cfs_find_service()->close(fd))
00192 #define cfs_read(fd, buf, len)  (cfs_find_service()->read(fd, buf, len))
00193 #define cfs_write(fd, buf, len) (cfs_find_service()->write(fd, buf, len))
00194 #define cfs_seek(fd, off)       (cfs_find_service()->seek(fd, off))
00195 
00196 #define cfs_opendir(dirp, name) (cfs_find_service()->opendir(dirp, name))
00197 #define cfs_readdir(dirp, ent)  (cfs_find_service()->readdir(dirp, ent))
00198 #define cfs_closedir(dirp)      (cfs_find_service()->closedir(dirp))
00199 
00200 
00201 #endif /* __CFS_H__ */
00202 
00203 /** @} */
00204 /** @} */

Generated on Thu Jun 22 17:45:42 2006 for Contiki 2.x by  doxygen 1.4.4