java.lang.Object | |
↳ | android.os.ParcelFileDescriptor |
The FileDescriptor returned by readFileDescriptor()
, allowing
you to close it when done with it.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
ParcelFileDescriptor.AutoCloseInputStream |
An InputStream you can create on a ParcelFileDescriptor, which will
take care of calling ParcelFileDescriptor.close() for you when the stream is closed.
|
||||||||||
ParcelFileDescriptor.AutoCloseOutputStream |
An OutputStream you can create on a ParcelFileDescriptor, which will
take care of calling ParcelFileDescriptor.close() for you when the stream is closed.
|
||||||||||
ParcelFileDescriptor.FileDescriptorDetachedException | Exception that indicates that the file descriptor was detached. | ||||||||||
ParcelFileDescriptor.OnCloseListener | Callback indicating that a ParcelFileDescriptor has been closed. |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | MODE_APPEND |
For use with open(File, int) : append to end of file while writing.
|
|||||||||
int | MODE_CREATE |
For use with open(File, int) : create the file if it doesn't already exist.
|
|||||||||
int | MODE_READ_ONLY |
For use with open(File, int) : open the file with read-only access.
|
|||||||||
int | MODE_READ_WRITE |
For use with open(File, int) : open the file with read and write access.
|
|||||||||
int | MODE_TRUNCATE |
For use with open(File, int) : erase contents of file when opening.
|
|||||||||
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.
|
|||||||||
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.
|
|||||||||
int | MODE_WRITE_ONLY |
For use with open(File, int) : open the file with write-only access.
|
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
![]() |
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
CREATOR |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create a new ParcelFileDescriptor wrapped around another descriptor.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Take ownership of a raw native fd in to a new ParcelFileDescriptor.
| |||||||||||
Indicates if this ParcelFileDescriptor can communicate and detect remote
errors/crashes.
| |||||||||||
Detect and throw if the other end of a pipe or socket pair encountered an
error or crashed.
| |||||||||||
Close the ParcelFileDescriptor.
| |||||||||||
Close the ParcelFileDescriptor, informing any peer that an error occurred
while processing.
| |||||||||||
Create two ParcelFileDescriptors structured as a data pipe.
| |||||||||||
Create two ParcelFileDescriptors structured as a data pipe.
| |||||||||||
Create two ParcelFileDescriptors structured as a pair of sockets
connected to each other.
| |||||||||||
Create two ParcelFileDescriptors structured as a pair of sockets
connected to each other.
| |||||||||||
Describe the kinds of special objects contained in this Parcelable's
marshalled representation.
| |||||||||||
Return the native fd int for this ParcelFileDescriptor and detach it from
the object here.
| |||||||||||
Create a new ParcelFileDescriptor that is a dup of an existing
FileDescriptor.
| |||||||||||
Create a new ParcelFileDescriptor that is a dup of the existing
FileDescriptor.
| |||||||||||
Create a new ParcelFileDescriptor from the specified DatagramSocket.
| |||||||||||
Create a new ParcelFileDescriptor from a raw native fd.
| |||||||||||
Create a new ParcelFileDescriptor from the specified Socket.
| |||||||||||
Return the native fd int for this ParcelFileDescriptor.
| |||||||||||
Retrieve the actual FileDescriptor associated with this object.
| |||||||||||
Return the total size of the file representing this fd, as determined by
stat() .
| |||||||||||
Create a new ParcelFileDescriptor accessing a given file.
| |||||||||||
Create a new ParcelFileDescriptor accessing a given file.
| |||||||||||
Converts a string representing a file mode, such as "rw", into a bitmask suitable for use
with
open(File, int) .
| |||||||||||
Returns a string containing a concise, human-readable description of this
object.
| |||||||||||
Flatten this object in to a Parcel.
If
PARCELABLE_WRITE_RETURN_VALUE is set in flags,
the file descriptor will be closed after a copy is written to the Parcel.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Invoked when the garbage collector has detected that this instance is no longer reachable.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
![]() | |||||||||||
![]() | |||||||||||
![]() | |||||||||||
![]() |
For use with open(File, int)
: append to end of file while writing.
For use with open(File, int)
: create the file if it doesn't already exist.
For use with open(File, int)
: open the file with read-only access.
For use with open(File, int)
: open the file with read and write access.
For use with open(File, int)
: erase contents of file when opening.
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.
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.
For use with open(File, int)
: open the file with write-only access.
Create a new ParcelFileDescriptor wrapped around another descriptor. By default all method calls are delegated to the wrapped descriptor.
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. You must not close the fd yourself.
fd | The native fd that the ParcelFileDescriptor should adopt. |
---|
Indicates if this ParcelFileDescriptor can communicate and detect remote errors/crashes.
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.
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(String) . |
Close the ParcelFileDescriptor. This implementation closes the underlying OS resources allocated to represent this stream.
IOException | If an error occurs attempting to close this ParcelFileDescriptor. |
---|
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.
msg | describing the error; must not be null. |
---|
IOException |
---|
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.
IOException |
---|
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(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.
IOException |
---|
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(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.
IOException |
---|
Create two ParcelFileDescriptors structured as a pair of sockets connected to each other. The two sockets are indistinguishable.
IOException |
---|
Describe the kinds of special objects contained in this Parcelable's marshalled representation.
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(String)
.
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.
IOException |
---|
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.
IOException |
---|
Create a new ParcelFileDescriptor from the specified DatagramSocket.
datagramSocket | The DatagramSocket whose FileDescriptor is used to create a new ParcelFileDescriptor. |
---|
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.
fd | The native fd that the ParcelFileDescriptor should dup. |
---|
IOException |
---|
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.
socket | The Socket whose FileDescriptor is used to create a new ParcelFileDescriptor. |
---|
Return the native fd int for this ParcelFileDescriptor. The ParcelFileDescriptor still owns the fd, and it still must be closed through this API.
Retrieve the actual FileDescriptor associated with this object.
Return the total size of the file representing this fd, as determined by
stat()
. Returns -1 if the fd is not a file.
Create a new ParcelFileDescriptor accessing a given file.
file | The file to be opened. |
---|---|
mode | 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 | to call listener from; must not be null. |
listener | to be invoked when the returned descriptor has been closed; must not be null. |
FileNotFoundException | if the given file does not exist or can not be opened with the requested mode. |
---|---|
IOException |
Create a new ParcelFileDescriptor accessing a given file.
file | The file to be opened. |
---|---|
mode | 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 . |
FileNotFoundException | if the given file does not exist or can not be opened with the requested mode. |
---|
Converts a string representing a file mode, such as "rw", into a bitmask suitable for use
with open(File, int)
.
mode | The string representation of the file mode. |
---|
IllegalArgumentException | if the given string does not match a known file mode. |
---|
Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression:
getClass().getName() + '@' + Integer.toHexString(hashCode())
See Writing a useful
toString
method
if you intend implementing your own toString
method.
Flatten this object in to a Parcel.
If PARCELABLE_WRITE_RETURN_VALUE
is set in flags,
the file descriptor will be closed after a copy is written to the Parcel.
out | The Parcel in which the object should be written. |
---|---|
flags | Additional flags about how the object should be written.
May be 0 or PARCELABLE_WRITE_RETURN_VALUE .
|
Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.
Note that objects that override finalize
are significantly more expensive than
objects that don't. Finalizers may be run a long time after the object is no longer
reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup.
Note also that finalizers are run on a single VM-wide finalizer thread,
so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary
for a class that has a native peer and needs to call a native method to destroy that peer.
Even then, it's better to provide an explicit close
method (and implement
Closeable
), and insist that callers manually dispose of instances. This
works well for something like files, but less well for something like a BigInteger
where typical calling code would have to deal with lots of temporaries. Unfortunately,
code that creates lots of temporaries is the worst kind of code from the point of view of
the single finalizer thread.
If you must use finalizers, consider at least providing your own
ReferenceQueue
and having your own thread process that queue.
Unlike constructors, finalizers are not automatically chained. You are responsible for
calling super.finalize()
yourself.
Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.
Throwable |
---|