ParcelFileDescriptor
public
class
ParcelFileDescriptor
extends Object
implements
Parcelable,
Closeable
java.lang.Object | |
↳ | android.os.ParcelFileDescriptor |
The FileDescriptor returned by Parcel#readFileDescriptor
, allowing
you to close it when done with it.
Summary
Nested classes | |
---|---|
class |
ParcelFileDescriptor.AutoCloseInputStream
An InputStream you can create on a ParcelFileDescriptor, which will
take care of calling |
class |
ParcelFileDescriptor.AutoCloseOutputStream
An OutputStream you can create on a ParcelFileDescriptor, which will
take care of calling |
class |
ParcelFileDescriptor.FileDescriptorDetachedException
Exception that indicates that the file descriptor was detached. |
interface |
ParcelFileDescriptor.OnCloseListener
Callback indicating that a ParcelFileDescriptor has been closed. |
Constants | |
---|---|
int |
MODE_APPEND
For use with |
int |
MODE_CREATE
For use with |
int |
MODE_READ_ONLY
For use with |
int |
MODE_READ_WRITE
For use with |
int |
MODE_TRUNCATE
For use with |
int |
MODE_WORLD_READABLE
This constant was deprecated
in API level 19.
Creating world-readable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as |
int |
MODE_WORLD_WRITEABLE
This constant was deprecated
in API level 19.
Creating world-writable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as |
int |
MODE_WRITE_ONLY
For use with |
Inherited constants |
---|
Fields | |
---|---|
public
static
final
Creator<ParcelFileDescriptor> |
CREATOR
|
Public constructors | |
---|---|
ParcelFileDescriptor(ParcelFileDescriptor wrapped)
Create a new ParcelFileDescriptor wrapped around another descriptor. |
Public methods | |
---|---|
static
ParcelFileDescriptor
|
adoptFd(int fd)
Take ownership of a raw native fd in to a new ParcelFileDescriptor. |
boolean
|
canDetectErrors()
Indicates if this ParcelFileDescriptor can communicate and detect remote errors/crashes. |
void
|
checkError()
Detect and throw if the other end of a pipe or socket pair encountered an error or crashed. |
void
|
close()
Close the ParcelFileDescriptor. |
void
|
closeWithError(String msg)
Close the ParcelFileDescriptor, informing any peer that an error occurred while processing. |
static
ParcelFileDescriptor[]
|
createPipe()
Create two ParcelFileDescriptors structured as a data pipe. |
static
ParcelFileDescriptor[]
|
createReliablePipe()
Create two ParcelFileDescriptors structured as a data pipe. |
static
ParcelFileDescriptor[]
|
createReliableSocketPair()
Create two ParcelFileDescriptors structured as a pair of sockets connected to each other. |
static
ParcelFileDescriptor[]
|
createSocketPair()
Create two ParcelFileDescriptors structured as a pair of sockets connected to each other. |
int
|
describeContents()
Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. |
int
|
detachFd()
Return the native fd int for this ParcelFileDescriptor and detach it from the object here. |
static
ParcelFileDescriptor
|
dup(FileDescriptor orig)
Create a new ParcelFileDescriptor that is a dup of an existing FileDescriptor. |
ParcelFileDescriptor
|
dup()
Create a new ParcelFileDescriptor that is a dup of the existing FileDescriptor. |
static
ParcelFileDescriptor
|
fromDatagramSocket(DatagramSocket datagramSocket)
Create a new ParcelFileDescriptor from the specified DatagramSocket. |
static
ParcelFileDescriptor
|
fromFd(int fd)
Create a new ParcelFileDescriptor from a raw native fd. |
static
ParcelFileDescriptor
|
fromSocket(Socket socket)
Create a new ParcelFileDescriptor from the specified Socket. |
int
|
getFd()
Return the native fd int for this ParcelFileDescriptor. |
FileDescriptor
|
getFileDescriptor()
Retrieve the actual FileDescriptor associated with this object. |
long
|
getStatSize()
Return the total size of the file representing this fd, as determined by
|
static
ParcelFileDescriptor
|
open(File file, int mode)
Create a new ParcelFileDescriptor accessing a given file. |
static
ParcelFileDescriptor
|
open(File file, int mode, Handler handler, ParcelFileDescriptor.OnCloseListener listener)
Create a new ParcelFileDescriptor accessing a given file. |
static
int
|
parseMode(String mode)
Converts a string representing a file mode, such as "rw", into a bitmask suitable for use
with |
String
|
toString()
Returns a string representation of the object. |
static
ParcelFileDescriptor
|
wrap(ParcelFileDescriptor pfd, Handler handler, ParcelFileDescriptor.OnCloseListener listener)
Create a new ParcelFileDescriptor wrapping an already-opened file. |
void
|
writeToParcel(Parcel out, int flags)
Flatten this object in to a Parcel.
If |
Protected methods | |
---|---|
void
|
finalize()
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. |
Inherited methods | |
---|---|
Constants
MODE_APPEND
public static final int MODE_APPEND
For use with open(File, int)
: append to end of file while writing.
Constant Value: 33554432 (0x02000000)
MODE_CREATE
public static final int MODE_CREATE
For use with open(File, int)
: create the file if it doesn't already exist.
Constant Value: 134217728 (0x08000000)
MODE_READ_ONLY
public static final int MODE_READ_ONLY
For use with open(File, int)
: open the file with read-only access.
Constant Value: 268435456 (0x10000000)
MODE_READ_WRITE
public static final int MODE_READ_WRITE
For use with open(File, int)
: open the file with read and write access.
Constant Value: 805306368 (0x30000000)
MODE_TRUNCATE
public static final int MODE_TRUNCATE
For use with open(File, int)
: erase contents of file when opening.
Constant Value: 67108864 (0x04000000)
MODE_WORLD_READABLE
public static final int MODE_WORLD_READABLE
This constant was deprecated
in API level 19.
Creating world-readable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as ContentProvider
,
BroadcastReceiver
, and Service
.
There are no guarantees that this access mode will remain on
a file, such as when it goes through a backup and restore.
For use with open(File, int)
: if MODE_CREATE
has been supplied and
this file doesn't already exist, then create the file with permissions
such that any application can read it.
Constant Value: 1 (0x00000001)
MODE_WORLD_WRITEABLE
public static final int MODE_WORLD_WRITEABLE
This constant was deprecated
in API level 19.
Creating world-writable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as ContentProvider
,
BroadcastReceiver
, and Service
.
There are no guarantees that this access mode will remain on
a file, such as when it goes through a backup and restore.
For use with open(File, int)
: if MODE_CREATE
has been supplied and
this file doesn't already exist, then create the file with permissions
such that any application can write it.
Constant Value: 2 (0x00000002)
MODE_WRITE_ONLY
public static final int MODE_WRITE_ONLY
For use with open(File, int)
: open the file with write-only access.
Constant Value: 536870912 (0x20000000)
Fields
Public constructors
ParcelFileDescriptor
public ParcelFileDescriptor (ParcelFileDescriptor wrapped)
Create a new ParcelFileDescriptor wrapped around another descriptor. By default all method calls are delegated to the wrapped descriptor.
Parameters | |
---|---|
wrapped |
ParcelFileDescriptor |
Public methods
adoptFd
public static ParcelFileDescriptor adoptFd (int fd)
Take ownership of a raw native fd in to a new ParcelFileDescriptor. The returned ParcelFileDescriptor now owns the given fd, and will be responsible for closing it.
WARNING: You must not close the fd yourself after this call, and ownership of the file descriptor must have been released prior to the call to this function.
Parameters | |
---|---|
fd |
int : The native fd that the ParcelFileDescriptor should adopt. |
Returns | |
---|---|
ParcelFileDescriptor |
Returns a new ParcelFileDescriptor holding a FileDescriptor for the given fd. |
canDetectErrors
public boolean canDetectErrors ()
Indicates if this ParcelFileDescriptor can communicate and detect remote errors/crashes.
Returns | |
---|---|
boolean |
See also:
checkError
public void checkError ()
Detect and throw if the other end of a pipe or socket pair encountered an error or crashed. This allows a reader to distinguish between a valid EOF and an error/crash.
If this ParcelFileDescriptor is unable to detect remote errors, it will return silently.
Throws | |
---|---|
IOException |
for normal errors. |
ParcelFileDescriptor.FileDescriptorDetachedException |
if the remote side called detachFd() . Once detached, the remote
side is unable to communicate any errors through
closeWithError(java.lang.String) . |
See also:
close
public void close ()
Close the ParcelFileDescriptor. This implementation closes the underlying OS resources allocated to represent this stream.
Throws | |
---|---|
IOException |
If an error occurs attempting to close this ParcelFileDescriptor. |
closeWithError
public void closeWithError (String msg)
Close the ParcelFileDescriptor, informing any peer that an error occurred while processing. If the creator of this descriptor is not observing errors, it will close normally.
Parameters | |
---|---|
msg |
String : describing the error; must not be null. |
Throws | |
---|---|
IOException |
createPipe
public static ParcelFileDescriptor[] createPipe ()
Create two ParcelFileDescriptors structured as a data pipe. The first ParcelFileDescriptor in the returned array is the read side; the second is the write side.
Returns | |
---|---|
ParcelFileDescriptor[] |
Throws | |
---|---|
IOException |
createReliablePipe
public static ParcelFileDescriptor[] createReliablePipe ()
Create two ParcelFileDescriptors structured as a data pipe. The first ParcelFileDescriptor in the returned array is the read side; the second is the write side.
The write end has the ability to deliver an error message through
closeWithError(java.lang.String)
which can be handled by the read end
calling checkError()
, usually after detecting an EOF.
This can also be used to detect remote crashes.
Returns | |
---|---|
ParcelFileDescriptor[] |
Throws | |
---|---|
IOException |
createReliableSocketPair
public static ParcelFileDescriptor[] createReliableSocketPair ()
Create two ParcelFileDescriptors structured as a pair of sockets connected to each other. The two sockets are indistinguishable.
Both ends have the ability to deliver an error message through
closeWithError(java.lang.String)
which can be detected by the other end
calling checkError()
, usually after detecting an EOF.
This can also be used to detect remote crashes.
Returns | |
---|---|
ParcelFileDescriptor[] |
Throws | |
---|---|
IOException |
createSocketPair
public static ParcelFileDescriptor[] createSocketPair ()
Create two ParcelFileDescriptors structured as a pair of sockets connected to each other. The two sockets are indistinguishable.
Returns | |
---|---|
ParcelFileDescriptor[] |
Throws | |
---|---|
IOException |
describeContents
public int describeContents ()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation. For example, if the object will
include a file descriptor in the output of writeToParcel(android.os.Parcel, int)
,
the return value of this method must include the
CONTENTS_FILE_DESCRIPTOR
bit.
Returns | |
---|---|
int |
a bitmask indicating the set of special object types marshaled
by this Parcelable object instance.
Value is either 0 or CONTENTS_FILE_DESCRIPTOR |
detachFd
public int detachFd ()
Return the native fd int for this ParcelFileDescriptor and detach it from the object here. You are now responsible for closing the fd in native code.
You should not detach when the original creator of the descriptor is
expecting a reliable signal through close()
or
closeWithError(java.lang.String)
.
Returns | |
---|---|
int |
See also:
dup
public static ParcelFileDescriptor dup (FileDescriptor orig)
Create a new ParcelFileDescriptor that is a dup of an existing FileDescriptor. This obeys standard POSIX semantics, where the new file descriptor shared state such as file position with the original file descriptor.
Parameters | |
---|---|
orig |
FileDescriptor |
Returns | |
---|---|
ParcelFileDescriptor |
Throws | |
---|---|
IOException |
dup
public ParcelFileDescriptor dup ()
Create a new ParcelFileDescriptor that is a dup of the existing FileDescriptor. This obeys standard POSIX semantics, where the new file descriptor shared state such as file position with the original file descriptor.
Returns | |
---|---|
ParcelFileDescriptor |
Throws | |
---|---|
IOException |
fromDatagramSocket
public static ParcelFileDescriptor fromDatagramSocket (DatagramSocket datagramSocket)
Create a new ParcelFileDescriptor from the specified DatagramSocket. The new ParcelFileDescriptor holds a dup of the original FileDescriptor in the DatagramSocket, so you must still close the DatagramSocket as well as the new ParcelFileDescriptor.
WARNING: Prior to API level 29, this function would not actually dup the DatagramSocket's FileDescriptor, and would take a reference to the its internal FileDescriptor instead. If the DatagramSocket gets garbage collected before the ParcelFileDescriptor, this may lead to the ParcelFileDescriptor being unexpectedly closed. To avoid this, the following pattern can be used:
ParcelFileDescriptor pfd = ParcelFileDescriptor.fromDatagramSocket(socket).dup();
Parameters | |
---|---|
datagramSocket |
DatagramSocket : The DatagramSocket whose FileDescriptor is used
to create a new ParcelFileDescriptor. |
Returns | |
---|---|
ParcelFileDescriptor |
A new ParcelFileDescriptor with a duped copy of the FileDescriptor of the specified Socket. |
Throws | |
---|---|
UncheckedIOException |
if dup(java.io.FileDescriptor) throws IOException. |
fromFd
public static ParcelFileDescriptor fromFd (int fd)
Create a new ParcelFileDescriptor from a raw native fd. The new ParcelFileDescriptor holds a dup of the original fd passed in here, so you must still close that fd as well as the new ParcelFileDescriptor.
Parameters | |
---|---|
fd |
int : The native fd that the ParcelFileDescriptor should dup. |
Returns | |
---|---|
ParcelFileDescriptor |
Returns a new ParcelFileDescriptor holding a FileDescriptor for a dup of the given fd. |
Throws | |
---|---|
IOException |
fromSocket
public static ParcelFileDescriptor fromSocket (Socket socket)
Create a new ParcelFileDescriptor from the specified Socket. The new ParcelFileDescriptor holds a dup of the original FileDescriptor in the Socket, so you must still close the Socket as well as the new ParcelFileDescriptor.
WARNING: Prior to API level 29, this function would not actually dup the Socket's FileDescriptor, and would take a reference to the its internal FileDescriptor instead. If the Socket gets garbage collected before the ParcelFileDescriptor, this may lead to the ParcelFileDescriptor being unexpectedly closed. To avoid this, the following pattern can be used:
ParcelFileDescriptor pfd = ParcelFileDescriptor.fromSocket(socket).dup();
Parameters | |
---|---|
socket |
Socket : The Socket whose FileDescriptor is used to create
a new ParcelFileDescriptor. |
Returns | |
---|---|
ParcelFileDescriptor |
A new ParcelFileDescriptor with a duped copy of the FileDescriptor of the specified Socket. |
Throws | |
---|---|
UncheckedIOException |
if dup(java.io.FileDescriptor) throws IOException. |
getFd
public int getFd ()
Return the native fd int for this ParcelFileDescriptor. The ParcelFileDescriptor still owns the fd, and it still must be closed through this API.
WARNING: Do not call close on the return value of this function or pass it to a function that assumes ownership of the fd.
Returns | |
---|---|
int |
getFileDescriptor
public FileDescriptor getFileDescriptor ()
Retrieve the actual FileDescriptor associated with this object.
Returns | |
---|---|
FileDescriptor |
Returns the FileDescriptor associated with this object. |
getStatSize
public long getStatSize ()
Return the total size of the file representing this fd, as determined by
stat()
. Returns -1 if the fd is not a file.
Returns | |
---|---|
long |
open
public static ParcelFileDescriptor open (File file, int mode)
Create a new ParcelFileDescriptor accessing a given file.
This method should only be used for files that you have direct access to;
if you'd like to work with files hosted outside your app, use an API like
ContentResolver#openFile(Uri, String, CancellationSignal)
.
Parameters | |
---|---|
file |
File : The file to be opened. |
mode |
int : The desired access mode, must be one of
MODE_READ_ONLY , MODE_WRITE_ONLY , or
MODE_READ_WRITE ; may also be any combination of
MODE_CREATE , MODE_TRUNCATE ,
MODE_WORLD_READABLE , and
MODE_WORLD_WRITEABLE . |
Returns | |
---|---|
ParcelFileDescriptor |
a new ParcelFileDescriptor pointing to the given file. |
Throws | |
---|---|
FileNotFoundException |
if the given file does not exist or can not be opened with the requested mode. |
See also:
open
public static ParcelFileDescriptor open (File file, int mode, Handler handler, ParcelFileDescriptor.OnCloseListener listener)
Create a new ParcelFileDescriptor accessing a given file.
This method should only be used for files that you have direct access to;
if you'd like to work with files hosted outside your app, use an API like
ContentResolver#openFile(Uri, String, CancellationSignal)
.
Parameters | |
---|---|
file |
File : The file to be opened. |
mode |
int : The desired access mode, must be one of
MODE_READ_ONLY , MODE_WRITE_ONLY , or
MODE_READ_WRITE ; may also be any combination of
MODE_CREATE , MODE_TRUNCATE ,
MODE_WORLD_READABLE , and
MODE_WORLD_WRITEABLE . |
handler |
Handler : to call listener from; must not be null. |
listener |
ParcelFileDescriptor.OnCloseListener : to be invoked when the returned descriptor has been
closed; must not be null. |
Returns | |
---|---|
ParcelFileDescriptor |
a new ParcelFileDescriptor pointing to the given file. |
Throws | |
---|---|
FileNotFoundException |
if the given file does not exist or can not be opened with the requested mode. |
IOException |
See also:
parseMode
public static int parseMode (String mode)
Converts a string representing a file mode, such as "rw", into a bitmask suitable for use
with open(File, int)
.
The argument must define at least one of the following base access modes:
- "r" indicates the file should be opened in read-only mode, equivalent
to
OsConstants#O_RDONLY
. - "w" indicates the file should be opened in write-only mode,
equivalent to
OsConstants#O_WRONLY
. - "rw" indicates the file should be opened in read-write mode,
equivalent to
OsConstants#O_RDWR
.
- "a" indicates the file should be opened in append mode, equivalent to
OsConstants#O_APPEND
. Before each write, the file offset is positioned at the end of the file. - "t" indicates the file should be opened in truncate mode, equivalent
to
OsConstants#O_TRUNC
. If the file already exists and is a regular file and is opened for writing, it will be truncated to length 0.
Parameters | |
---|---|
mode |
String : The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw"
or "rwt". |
Returns | |
---|---|
int |
A bitmask representing the given file mode. |
Throws | |
---|---|
IllegalArgumentException |
if the given string does not match a known file mode. |
toString
public String toString ()
Returns a string representation of the object.
Returns | |
---|---|
String |
a string representation of the object. |
wrap
public static ParcelFileDescriptor wrap (ParcelFileDescriptor pfd, Handler handler, ParcelFileDescriptor.OnCloseListener listener)
Create a new ParcelFileDescriptor wrapping an already-opened file.
Parameters | |
---|---|
pfd |
ParcelFileDescriptor : The already-opened file.
This value cannot be null . |
handler |
Handler : to call listener from.
This value cannot be null . |
listener |
ParcelFileDescriptor.OnCloseListener : to be invoked when the returned descriptor has been
closed.
This value cannot be null . |
Returns | |
---|---|
ParcelFileDescriptor |
a new ParcelFileDescriptor pointing to the given file.
This value cannot be null . |
Throws | |
---|---|
IOException |
writeToParcel
public void writeToParcel (Parcel out, int flags)
Flatten this object in to a Parcel.
If Parcelable#PARCELABLE_WRITE_RETURN_VALUE
is set in flags,
the file descriptor will be closed after a copy is written to the Parcel.
Parameters | |
---|---|
out |
Parcel : The Parcel in which the object should be written.
This value cannot be null . |
flags |
int : Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE .
Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE , and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES |
Protected methods
finalize
protected void finalize ()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
A subclass overrides the finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the Java virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.
Throws | |
---|---|
Throwable |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-04-11 UTC.