Commit 4f82d2a5 authored by jdelange's avatar jdelange

* po_hi_storage.h

   - Description of the storage function



git-svn-id: https://tecsw.estec.esa.int/svn/taste/trunk/po-hi-c@3482 129961e7-ef38-4bb5-a8f7-c9a525a55882
parent 5919e2f0
......@@ -54,6 +54,13 @@ typedef struct
} __po_hi_storage_packet_store_t;
typedef struct
{
__po_hi_uint32_t n_packets; /*< number of packets in the store > */
__po_hi_uint32_t n_avail; /*< available packets size > */
__po_hi_uint8_t full; /*< is the store full ?> */
}__po_hi_storage_packet_store_status_t;
/*
* Files operations
*/
......@@ -236,22 +243,159 @@ int __po_hi_storage_file_unlock (const __po_hi_storage_file_t* file);
* Directory operations
*/
/**
* \fn __po_hi_storage_directory_open
*
* \brief Open a directory designated under the name associated in the first
* parameter. The second parameter is the directory structure to be
* initialized.
*
* Please note that this function just fills the structure passed as the
* second parameter. It does not create the directory itself
* on the real filesystem, this is supposed to be done by a separate
* function (__po_hi_storage_directory_create).
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS: successful operation
* - __PO_HI_TOOMANY: too may directories are open at this time, cannot open more.
* - __PO_HI_INVALID: supplied directory name is invalid
*/
int __po_hi_storage_directory_open (const char*, __po_hi_storage_dir_t*);
/**
* \fn __po_hi_storage_directory_create
*
* \brief Create a directory.
*
* Create a directory designated in the first parameter (previously
* created using the __po_hi_storage_directory_open() function).
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_INVALID : invalid directory structure
* - __PO_HI_ERROR_EXISTS : directory already exists
*/
int __po_hi_storage_directory_create (const __po_hi_storage_dir_t*);
/**
* \fn __po_hi_storage_directory_delete
*
* \brief Delete a directory.
*
* Delete a directory designated in the first parameter (previously
* created using the __po_hi_storage_directory_open() function).
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_INVALID : invalid directory structure
* - __PO_HI_ERROR_NOEXISTS : directory does not exist
*/
int __po_hi_storage_directory_delete (const __po_hi_storage_dir_t*);
/**
* \fn __po_hi_storage_directory_rename
*
* \brief Rename a directory.
*
* Rename a directory designated in the first parameter (previously
* created using the __po_hi_storage_directory_open() function) with
* the name of the directory supplied in the second argument
* (also created using the __po_hi_storage_directory_open() function).
* After successful call, the directory will not be available under the name
* of the first argument.
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_INVALID : invalid directory structure
* - __PO_HI_ERROR_NOEXISTS : directory of the first parameter does not
* exist
* - __PO_HI_ERROR_EXISTS : directory of the second parameter already
* exist
*/
int __po_hi_storage_directory_rename (const __po_hi_storage_dir_t* oldname, const __po_hi_storage_dir_t* newname);
/**
* \fn __po_hi_storage_directory_list
*
* \brief List the content of the directory.
*
* This function fills the __po_hi_storage_dir_t structure
* passed as argument with all the necessary content (files
* contained in the directory, etc.).
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_INVALID : invalid directory structure
* - __PO_HI_ERROR_NOEXISTS : the directory does not exist.
*/
int __po_hi_storage_directory_list (const __po_hi_storage_dir_t* dir);
/**
* \fn __po_hi_storage_directory_lock
*
* \brief Lock a directory.
*
* Lock a directory so that it ensures an exclusive access for
* a task. It acts as a mutex: if the lock was already acquired,
* a second call will make the second caller waiting for the lock to be
* released.
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_INVALID : invalid directory structure
*/
int __po_hi_storage_directory_lock (const __po_hi_storage_dir_t* dir);
/**
* \fn __po_hi_storage_directory_unlock
*
* \brief Unlock a directory.
*
* Unlock a previously locked directory. It releases the mutex associated
* to the mutex so that other task can locks the resource again.
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_INVALID : invalid directory structure
* - __PO_HI_UNAVAILABLE : the directory was not locked.
*/
int __po_hi_storage_directory_unlock (const __po_hi_storage_dir_t* dir);
/**
* \fn __po_hi_storage_change_cdir
*
* \brief Change the current directory of a task
*
* Change the directory associated with the current execution
* context of the task.
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_INVALID : invalid directory structure
* - __PO_HI_NOEXISTS : the directory does not exists
*/
int __po_hi_storage_change_cdir (__po_hi_storage_dir_t* new_current_directory);
/**
* \fn __po_hi_storage_get_cdir
*
* \brief Get the current directory of the operating task
*
* Change the directory associated with the current execution
* context of the task.
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
*/
int __po_hi_storage_get_cdir (__po_hi_storage_dir_t* current_directory);
......@@ -259,20 +403,126 @@ int __po_hi_storage_get_cdir (__po_hi_storage_dir_t* current_directory);
* Packets service
*/
/**
* \fn __po_hi_storage_packet_store_new
*
* \brief Create a new packet store
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_TOOMANY : too many store already created
*/
int __po_hi_storage_packet_store_new (__po_hi_storage_packet_store_t* store);
/**
* \fn __po_hi_storage_packet_store_new_from_file
*
* \brief Create a new packet store with the data stored in a file.
*
* The first argument is the store that would contain the packets
* while the second argument is the file that contain the packet
* store data (created during a previous execution with
* __po_hi_storage_packet_store_zrite_to_file ())
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_TOOMANY : too many store already created
* - __PO_HI_NOEXISTS : file does not exists (second argument)
*/
int __po_hi_storage_packet_store_new_from_file (__po_hi_storage_packet_store_t* store, __po_hi_storage_file_t* file);
/**
* \fn __po_hi_storage_packet_store_write_to_file
*
* \brief Write the content of a packet store to a file.
*
* The first argument is the store that would contain the packets
* while the second argument is the file that would be created.
* This functions assumes the destination file does not exists.
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_TOOMANY : too many store already created
* - __PO_HI_EXISTS : file already exists (second argument)
*/
int __po_hi_storage_packet_store_write_to_file (__po_hi_storage_packet_store_t* store, __po_hi_storage_file_t* file);
/**
* \fn __po_hi_storage_packet_store_read
*
* \brief Read a packet from a packet store.
*
* The first argument is the store while the second argument
* is the packet to be read (contain the information/data of
* the packet). If the store does not contain any packet, the function
* returns an error.
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_UNAVAILABLE : no packet to be read.
* - __PO_HI_INVALID : invalid packet store or packet to write
* (invalid address)
*/
int __po_hi_storage_packet_store_read (__po_hi_storage_packet_store_t* store, __po_hi_storage_packet_t*);
/**
* \fn __po_hi_storage_packet_store_write
*
* \brief Write a packet to a packet store.
*
* The first argument is the store while the second argument
* is the packet to be written (contain the information/data of
* the packet).
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_TOOMANY : the store contains already too many
* packets, cannot write more packets.
* - __PO_HI_INVALID : invalid packet store or packet to write
* (invalid address)
*/
int __po_hi_storage_packet_store_write (__po_hi_storage_packet_store_t* store, __po_hi_storage_packet_t*);
/**
* \fn __po_hi_storage_packet_store_free
*
* \brief Free old packets from a store.
*
* The first argument is the store while the second argument
* is the number of packets to free.
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_NOEXISTS : the user ask to free more packets
* than the quantity of available in the
* store. So, all packets are free'ed and the
* function returns __PO_HI_NOEXISTS.
* - __PO_HI_INVALID : invalid packet store or packet to write
* (invalid address)
*/
int __po_hi_storage_packet_store_free (__po_hi_storage_packet_store_t* store, int n_free);
/**
* \fn __po_hi_storage_packet_store_status
*
* \brief Indicate the status of a packet store.
*
* The first argument is the store while the second argument
* is the status structure that would be filled by the function.
*
* Upon success, the function returns __PO_HI_SUCCESS.
* It returns the following potential values:
* - __PO_HI_SUCCESS : successful operation
* - __PO_HI_INVALID : invalid packet store or invalid structure
* (invalid address)
*/
int __po_hi_storage_packet_store_status (__po_hi_storage_packet_store_t* store, __po_hi_storage_packet_store_status_t* status);
#endif /* __PO_HI_STORAGE_H__ */
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment