mbed-dev_spine - mbed library sources. Supersedes mbed-src.

Users » benkatz » Code » mbed-dev_spine

Ben Katz / mbed-dev_spine

mbed library sources. Supersedes mbed-src.

Dependents: SPIne CH_Communicatuin_Test CH_Communicatuin_Test2 MCP_SPIne ... more

Fork of mbed-dev-f303 by Ben Katz

platform/FileHandle.h@179:97f825502e2a, 2018-05-02 (annotated)

Committer:: benkatz
Date:: Wed May 02 18:08:16 2018 +0000
Revision:: 179:97f825502e2a
Parent:: 168:9672193075cf

Who changed what in which revision?

User	Revision	Line number	New contents of line
AnnaBridge	167:e84263d55307	1	/* mbed Microcontroller Library
AnnaBridge	167:e84263d55307	2	* Copyright (c) 2017 ARM Limited
AnnaBridge	167:e84263d55307	3	*
AnnaBridge	167:e84263d55307	4	* Licensed under the Apache License, Version 2.0 (the "License");
AnnaBridge	167:e84263d55307	5	* you may not use this file except in compliance with the License.
AnnaBridge	167:e84263d55307	6	* You may obtain a copy of the License at
AnnaBridge	167:e84263d55307	7	*
AnnaBridge	167:e84263d55307	8	* http://www.apache.org/licenses/LICENSE-2.0
AnnaBridge	167:e84263d55307	9	*
AnnaBridge	167:e84263d55307	10	* Unless required by applicable law or agreed to in writing, software
AnnaBridge	167:e84263d55307	11	* distributed under the License is distributed on an "AS IS" BASIS,
AnnaBridge	167:e84263d55307	12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
AnnaBridge	167:e84263d55307	13	* See the License for the specific language governing permissions and
AnnaBridge	167:e84263d55307	14	* limitations under the License.
AnnaBridge	167:e84263d55307	15	*/
AnnaBridge	167:e84263d55307	16	#ifndef MBED_FILEHANDLE_H
AnnaBridge	167:e84263d55307	17	#define MBED_FILEHANDLE_H
AnnaBridge	167:e84263d55307	18
AnnaBridge	167:e84263d55307	19	typedef int FILEHANDLE;
AnnaBridge	167:e84263d55307	20
AnnaBridge	167:e84263d55307	21	#include <cstdio>
AnnaBridge	167:e84263d55307	22	#include "Callback.h"
AnnaBridge	167:e84263d55307	23	#include "platform/mbed_poll.h"
AnnaBridge	167:e84263d55307	24	#include "platform/platform.h"
AnnaBridge	168:9672193075cf	25	#include "platform/NonCopyable.h"
AnnaBridge	167:e84263d55307	26
AnnaBridge	167:e84263d55307	27	namespace mbed {
AnnaBridge	167:e84263d55307	28	/** \addtogroup platform */
AnnaBridge	167:e84263d55307	29
AnnaBridge	167:e84263d55307	30
AnnaBridge	167:e84263d55307	31	/** Class FileHandle
AnnaBridge	167:e84263d55307	32	*
AnnaBridge	167:e84263d55307	33	* An abstract interface that represents operations on a file-like
AnnaBridge	167:e84263d55307	34	* object. The core functions are read, write, and seek, but only
AnnaBridge	167:e84263d55307	35	* a subset of these operations can be provided.
AnnaBridge	167:e84263d55307	36	*
AnnaBridge	167:e84263d55307	37	* @note to create a file, @see File
AnnaBridge	167:e84263d55307	38	* @note Synchronization level: Set by subclass
AnnaBridge	167:e84263d55307	39	* @ingroup platform
AnnaBridge	167:e84263d55307	40	*/
AnnaBridge	168:9672193075cf	41	class FileHandle : private NonCopyable<FileHandle> {
AnnaBridge	167:e84263d55307	42	public:
AnnaBridge	167:e84263d55307	43	virtual ~FileHandle() {}
AnnaBridge	167:e84263d55307	44
AnnaBridge	167:e84263d55307	45	/** Read the contents of a file into a buffer
AnnaBridge	167:e84263d55307	46	*
AnnaBridge	167:e84263d55307	47	* Devices acting as FileHandles should follow POSIX semantics:
AnnaBridge	167:e84263d55307	48	*
AnnaBridge	167:e84263d55307	49	* * if no data is available, and non-blocking set return -EAGAIN
AnnaBridge	167:e84263d55307	50	* * if no data is available, and blocking set, wait until data is available
AnnaBridge	167:e84263d55307	51	* * If any data is available, call returns immediately
AnnaBridge	167:e84263d55307	52	*
AnnaBridge	167:e84263d55307	53	* @param buffer The buffer to read in to
AnnaBridge	167:e84263d55307	54	* @param size The number of bytes to read
AnnaBridge	167:e84263d55307	55	* @return The number of bytes read, 0 at end of file, negative error on failure
AnnaBridge	167:e84263d55307	56	*/
AnnaBridge	167:e84263d55307	57	virtual ssize_t read(void *buffer, size_t size) = 0;
AnnaBridge	167:e84263d55307	58
AnnaBridge	167:e84263d55307	59	/** Write the contents of a buffer to a file
AnnaBridge	167:e84263d55307	60	*
AnnaBridge	167:e84263d55307	61	* @param buffer The buffer to write from
AnnaBridge	167:e84263d55307	62	* @param size The number of bytes to write
AnnaBridge	167:e84263d55307	63	* @return The number of bytes written, negative error on failure
AnnaBridge	167:e84263d55307	64	*/
AnnaBridge	167:e84263d55307	65	virtual ssize_t write(const void *buffer, size_t size) = 0;
AnnaBridge	167:e84263d55307	66
AnnaBridge	167:e84263d55307	67	/** Move the file position to a given offset from from a given location
AnnaBridge	167:e84263d55307	68	*
AnnaBridge	167:e84263d55307	69	* @param offset The offset from whence to move to
AnnaBridge	167:e84263d55307	70	* @param whence The start of where to seek
AnnaBridge	167:e84263d55307	71	* SEEK_SET to start from beginning of file,
AnnaBridge	167:e84263d55307	72	* SEEK_CUR to start from current position in file,
AnnaBridge	167:e84263d55307	73	* SEEK_END to start from end of file
AnnaBridge	167:e84263d55307	74	* @return The new offset of the file, negative error code on failure
AnnaBridge	167:e84263d55307	75	*/
AnnaBridge	167:e84263d55307	76	virtual off_t seek(off_t offset, int whence = SEEK_SET) = 0;
AnnaBridge	167:e84263d55307	77
AnnaBridge	167:e84263d55307	78	/** Close a file
AnnaBridge	167:e84263d55307	79	*
AnnaBridge	167:e84263d55307	80	* @return 0 on success, negative error code on failure
AnnaBridge	167:e84263d55307	81	*/
AnnaBridge	167:e84263d55307	82	virtual int close() = 0;
AnnaBridge	167:e84263d55307	83
AnnaBridge	167:e84263d55307	84	/** Flush any buffers associated with the file
AnnaBridge	167:e84263d55307	85	*
AnnaBridge	167:e84263d55307	86	* @return 0 on success, negative error code on failure
AnnaBridge	167:e84263d55307	87	*/
AnnaBridge	167:e84263d55307	88	virtual int sync()
AnnaBridge	167:e84263d55307	89	{
AnnaBridge	167:e84263d55307	90	return 0;
AnnaBridge	167:e84263d55307	91	}
AnnaBridge	167:e84263d55307	92
AnnaBridge	167:e84263d55307	93	/** Check if the file in an interactive terminal device
AnnaBridge	167:e84263d55307	94	*
AnnaBridge	167:e84263d55307	95	* @return True if the file is a terminal
AnnaBridge	167:e84263d55307	96	* @return False if the file is not a terminal
AnnaBridge	167:e84263d55307	97	* @return Negative error code on failure
AnnaBridge	167:e84263d55307	98	*/
AnnaBridge	167:e84263d55307	99	virtual int isatty()
AnnaBridge	167:e84263d55307	100	{
AnnaBridge	167:e84263d55307	101	return false;
AnnaBridge	167:e84263d55307	102	}
AnnaBridge	167:e84263d55307	103
AnnaBridge	167:e84263d55307	104	/** Get the file position of the file
AnnaBridge	167:e84263d55307	105	*
AnnaBridge	167:e84263d55307	106	* @note This is equivalent to seek(0, SEEK_CUR)
AnnaBridge	167:e84263d55307	107	*
AnnaBridge	167:e84263d55307	108	* @return The current offset in the file, negative error code on failure
AnnaBridge	167:e84263d55307	109	*/
AnnaBridge	167:e84263d55307	110	virtual off_t tell()
AnnaBridge	167:e84263d55307	111	{
AnnaBridge	167:e84263d55307	112	return seek(0, SEEK_CUR);
AnnaBridge	167:e84263d55307	113	}
AnnaBridge	167:e84263d55307	114
AnnaBridge	167:e84263d55307	115	/** Rewind the file position to the beginning of the file
AnnaBridge	167:e84263d55307	116	*
AnnaBridge	167:e84263d55307	117	* @note This is equivalent to seek(0, SEEK_SET)
AnnaBridge	167:e84263d55307	118	*/
AnnaBridge	167:e84263d55307	119	virtual void rewind()
AnnaBridge	167:e84263d55307	120	{
AnnaBridge	167:e84263d55307	121	seek(0, SEEK_SET);
AnnaBridge	167:e84263d55307	122	}
AnnaBridge	167:e84263d55307	123
AnnaBridge	167:e84263d55307	124	/** Get the size of the file
AnnaBridge	167:e84263d55307	125	*
AnnaBridge	167:e84263d55307	126	* @return Size of the file in bytes
AnnaBridge	167:e84263d55307	127	*/
AnnaBridge	167:e84263d55307	128	virtual off_t size();
AnnaBridge	167:e84263d55307	129
AnnaBridge	167:e84263d55307	130	/** Move the file position to a given offset from a given location.
AnnaBridge	167:e84263d55307	131	*
AnnaBridge	167:e84263d55307	132	* @param offset The offset from whence to move to
AnnaBridge	167:e84263d55307	133	* @param whence SEEK_SET for the start of the file, SEEK_CUR for the
AnnaBridge	167:e84263d55307	134	* current file position, or SEEK_END for the end of the file.
AnnaBridge	167:e84263d55307	135	*
AnnaBridge	167:e84263d55307	136	* @returns
AnnaBridge	167:e84263d55307	137	* new file position on success,
AnnaBridge	167:e84263d55307	138	* -1 on failure or unsupported
AnnaBridge	167:e84263d55307	139	*/
AnnaBridge	167:e84263d55307	140	MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::seek")
AnnaBridge	167:e84263d55307	141	virtual off_t lseek(off_t offset, int whence)
AnnaBridge	167:e84263d55307	142	{
AnnaBridge	167:e84263d55307	143	return seek(offset, whence);
AnnaBridge	167:e84263d55307	144	}
AnnaBridge	167:e84263d55307	145
AnnaBridge	167:e84263d55307	146	/** Flush any buffers associated with the FileHandle, ensuring it
AnnaBridge	167:e84263d55307	147	* is up to date on disk
AnnaBridge	167:e84263d55307	148	*
AnnaBridge	167:e84263d55307	149	* @returns
AnnaBridge	167:e84263d55307	150	* 0 on success or un-needed,
AnnaBridge	167:e84263d55307	151	* -1 on error
AnnaBridge	167:e84263d55307	152	*/
AnnaBridge	167:e84263d55307	153	MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::sync")
AnnaBridge	167:e84263d55307	154	virtual int fsync()
AnnaBridge	167:e84263d55307	155	{
AnnaBridge	167:e84263d55307	156	return sync();
AnnaBridge	167:e84263d55307	157	}
AnnaBridge	167:e84263d55307	158
AnnaBridge	167:e84263d55307	159	/** Find the length of the file
AnnaBridge	167:e84263d55307	160	*
AnnaBridge	167:e84263d55307	161	* @returns
AnnaBridge	167:e84263d55307	162	* Length of the file
AnnaBridge	167:e84263d55307	163	*/
AnnaBridge	167:e84263d55307	164	MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::size")
AnnaBridge	167:e84263d55307	165	virtual off_t flen()
AnnaBridge	167:e84263d55307	166	{
AnnaBridge	167:e84263d55307	167	return size();
AnnaBridge	167:e84263d55307	168	}
AnnaBridge	167:e84263d55307	169
AnnaBridge	167:e84263d55307	170	/** Set blocking or non-blocking mode of the file operation like read/write.
AnnaBridge	167:e84263d55307	171	* Definition depends upon the subclass implementing FileHandle.
AnnaBridge	167:e84263d55307	172	* The default is blocking.
AnnaBridge	167:e84263d55307	173	*
AnnaBridge	167:e84263d55307	174	* @param blocking true for blocking mode, false for non-blocking mode.
AnnaBridge	167:e84263d55307	175	*
AnnaBridge	167:e84263d55307	176	* @return 0 on success
AnnaBridge	167:e84263d55307	177	* @return Negative error code on failure
AnnaBridge	167:e84263d55307	178	*/
AnnaBridge	167:e84263d55307	179	virtual int set_blocking(bool blocking)
AnnaBridge	167:e84263d55307	180	{
AnnaBridge	167:e84263d55307	181	return -1;
AnnaBridge	167:e84263d55307	182	}
AnnaBridge	167:e84263d55307	183
AnnaBridge	167:e84263d55307	184	/** Check for poll event flags
AnnaBridge	167:e84263d55307	185	* The input parameter can be used or ignored - the could always return all events,
AnnaBridge	167:e84263d55307	186	* or could check just the events listed in events.
AnnaBridge	167:e84263d55307	187	* Call is non-blocking - returns instantaneous state of events.
AnnaBridge	167:e84263d55307	188	* Whenever an event occurs, the derived class should call the sigio() callback).
AnnaBridge	167:e84263d55307	189	*
AnnaBridge	167:e84263d55307	190	* @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc.
AnnaBridge	167:e84263d55307	191	*
AnnaBridge	167:e84263d55307	192	* @returns bitmask of poll events that have occurred.
AnnaBridge	167:e84263d55307	193	*/
AnnaBridge	167:e84263d55307	194	virtual short poll(short events) const
AnnaBridge	167:e84263d55307	195	{
AnnaBridge	167:e84263d55307	196	// Possible default for real files
AnnaBridge	167:e84263d55307	197	return POLLIN \| POLLOUT;
AnnaBridge	167:e84263d55307	198	}
AnnaBridge	167:e84263d55307	199
AnnaBridge	167:e84263d55307	200	/** Definition depends upon the subclass implementing FileHandle.
AnnaBridge	167:e84263d55307	201	* For example, if the FileHandle is of type Stream, writable() could return
AnnaBridge	167:e84263d55307	202	* true when there is ample buffer space available for write() calls.
AnnaBridge	167:e84263d55307	203	*
AnnaBridge	167:e84263d55307	204	* @returns true if the FileHandle is writable.
AnnaBridge	167:e84263d55307	205	*/
AnnaBridge	167:e84263d55307	206	bool writable() const
AnnaBridge	167:e84263d55307	207	{
AnnaBridge	167:e84263d55307	208	return poll(POLLOUT) & POLLOUT;
AnnaBridge	167:e84263d55307	209	}
AnnaBridge	167:e84263d55307	210
AnnaBridge	167:e84263d55307	211	/** Definition depends upon the subclass implementing FileHandle.
AnnaBridge	167:e84263d55307	212	* For example, if the FileHandle is of type Stream, readable() could return
AnnaBridge	167:e84263d55307	213	* true when there is something available to read.
AnnaBridge	167:e84263d55307	214	*
AnnaBridge	167:e84263d55307	215	* @returns true when there is something available to read.
AnnaBridge	167:e84263d55307	216	*/
AnnaBridge	167:e84263d55307	217	bool readable() const
AnnaBridge	167:e84263d55307	218	{
AnnaBridge	167:e84263d55307	219	return poll(POLLIN) & POLLIN;
AnnaBridge	167:e84263d55307	220	}
AnnaBridge	167:e84263d55307	221
AnnaBridge	167:e84263d55307	222	/** Register a callback on state change of the file.
AnnaBridge	167:e84263d55307	223	*
AnnaBridge	167:e84263d55307	224	* The specified callback will be called on state changes such as when
AnnaBridge	167:e84263d55307	225	* the file can be written to or read from.
AnnaBridge	167:e84263d55307	226	*
AnnaBridge	167:e84263d55307	227	* The callback may be called in an interrupt context and should not
AnnaBridge	167:e84263d55307	228	* perform expensive operations.
AnnaBridge	167:e84263d55307	229	*
AnnaBridge	167:e84263d55307	230	* Note! This is not intended as an attach-like asynchronous api, but rather
AnnaBridge	167:e84263d55307	231	* as a building block for constructing such functionality.
AnnaBridge	167:e84263d55307	232	*
AnnaBridge	167:e84263d55307	233	* The exact timing of when the registered function
AnnaBridge	167:e84263d55307	234	* is called is not guaranteed and susceptible to change. It should be used
AnnaBridge	167:e84263d55307	235	* as a cue to make read/write/poll calls to find the current state.
AnnaBridge	167:e84263d55307	236	*
AnnaBridge	167:e84263d55307	237	* @param func Function to call on state change
AnnaBridge	167:e84263d55307	238	*/
AnnaBridge	167:e84263d55307	239	virtual void sigio(Callback<void()> func)
AnnaBridge	167:e84263d55307	240	{
AnnaBridge	167:e84263d55307	241	//Default for real files. Do nothing for real files.
AnnaBridge	167:e84263d55307	242	}
AnnaBridge	167:e84263d55307	243	};
AnnaBridge	167:e84263d55307	244
AnnaBridge	167:e84263d55307	245	/** Not a member function
AnnaBridge	167:e84263d55307	246	* This call is equivalent to posix fdopen().
AnnaBridge	167:e84263d55307	247	* It associates a Stream to an already opened file descriptor (FileHandle)
AnnaBridge	167:e84263d55307	248	*
AnnaBridge	167:e84263d55307	249	* @param fh a pointer to an opened file descriptor
AnnaBridge	167:e84263d55307	250	* @param mode operation upon the file descriptor, e.g., 'wb+'
AnnaBridge	167:e84263d55307	251	*
AnnaBridge	167:e84263d55307	252	* @returns a pointer to std::FILE
AnnaBridge	167:e84263d55307	253	*/
AnnaBridge	167:e84263d55307	254
AnnaBridge	167:e84263d55307	255	std::FILE fdopen(FileHandle fh, const char *mode);
AnnaBridge	167:e84263d55307	256
AnnaBridge	167:e84263d55307	257	} // namespace mbed
AnnaBridge	167:e84263d55307	258
AnnaBridge	167:e84263d55307	259	#endif

Repository toolbox

Export to desktop IDE

Repository details

Type:	Library
Created:	02 May 2018
Imports:	22
Forks:	0
Commits:	180
Dependents:	11
Dependencies:	0
Followers:	9

This repository is Public (Unlisted).

platform/FileHandle.h@179:97f825502e2a, 2018-05-02 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning