public class ParcelFileDescriptor extends Object implements Parcelable, Closeable
Parcel.readFileDescriptor()
, allowing
you to close it when done with it.Modifier and Type | Class and Description |
---|---|
static class |
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. |
static class |
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. |
static class |
ParcelFileDescriptor.FileDescriptorDetachedException
Exception that indicates that the file descriptor was detached.
|
static interface |
ParcelFileDescriptor.OnCloseListener
Callback indicating that a ParcelFileDescriptor has been closed.
|
Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>
Modifier and Type | Field and Description |
---|---|
static Parcelable.Creator<ParcelFileDescriptor> |
CREATOR |
static int |
MODE_APPEND
For use with
open(java.io.File, int) : append to end of file while writing. |
static int |
MODE_CREATE
For use with
open(java.io.File, int) : create the file if it doesn't already exist. |
static int |
MODE_READ_ONLY
For use with
open(java.io.File, int) : open the file with read-only access. |
static int |
MODE_READ_WRITE
For use with
open(java.io.File, int) : open the file with read and write access. |
static int |
MODE_TRUNCATE
For use with
open(java.io.File, int) : erase contents of file when opening. |
static int |
MODE_WORLD_READABLE
Deprecated.
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. |
static int |
MODE_WORLD_WRITEABLE
Deprecated.
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. |
static int |
MODE_WRITE_ONLY
For use with
open(java.io.File, int) : open the file with write-only access. |
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_ELIDE_DUPLICATES, PARCELABLE_WRITE_RETURN_VALUE
Constructor and Description |
---|
ParcelFileDescriptor(FileDescriptor fd) |
ParcelFileDescriptor(FileDescriptor fd,
FileDescriptor commChannel) |
ParcelFileDescriptor(ParcelFileDescriptor wrapped)
Create a new ParcelFileDescriptor wrapped around another descriptor.
|
Modifier and Type | Method and Description |
---|---|
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[] |
createReliableSocketPair(int type) |
static ParcelFileDescriptor[] |
createSocketPair()
Create two ParcelFileDescriptors structured as a pair of sockets
connected to each other.
|
static ParcelFileDescriptor[] |
createSocketPair(int type) |
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.
|
ParcelFileDescriptor |
dup()
Create a new ParcelFileDescriptor that is a dup of the existing
FileDescriptor.
|
static ParcelFileDescriptor |
dup(FileDescriptor orig)
Create a new ParcelFileDescriptor that is a dup of an existing
FileDescriptor.
|
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
static ParcelFileDescriptor |
fromData(byte[] data,
String name)
Deprecated.
|
static ParcelFileDescriptor |
fromDatagramSocket(DatagramSocket datagramSocket)
Create a new ParcelFileDescriptor from the specified DatagramSocket.
|
static ParcelFileDescriptor |
fromFd(FileDescriptor fd,
Handler handler,
ParcelFileDescriptor.OnCloseListener listener) |
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
stat() . |
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
open(java.io.File, int) . |
void |
releaseResources()
Called when the fd is being closed, for subclasses to release any other resources
associated with it, such as acquired providers.
|
long |
seekTo(long pos)
This is needed for implementing AssetFileDescriptor.AutoCloseOutputStream,
and I really don't think we want it to be public.
|
String |
toString()
Returns a string representation of the object.
|
void |
writeToParcel(Parcel out,
int flags)
Flatten this object in to a Parcel.
|
@Deprecated public static final int MODE_WORLD_READABLE
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.open(java.io.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.@Deprecated public static final int MODE_WORLD_WRITEABLE
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.open(java.io.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.public static final int MODE_READ_ONLY
open(java.io.File, int)
: open the file with read-only access.public static final int MODE_WRITE_ONLY
open(java.io.File, int)
: open the file with write-only access.public static final int MODE_READ_WRITE
open(java.io.File, int)
: open the file with read and write access.public static final int MODE_CREATE
open(java.io.File, int)
: create the file if it doesn't already exist.public static final int MODE_TRUNCATE
open(java.io.File, int)
: erase contents of file when opening.public static final int MODE_APPEND
open(java.io.File, int)
: append to end of file while writing.public static final Parcelable.Creator<ParcelFileDescriptor> CREATOR
public ParcelFileDescriptor(ParcelFileDescriptor wrapped)
public ParcelFileDescriptor(FileDescriptor fd)
public ParcelFileDescriptor(FileDescriptor fd, FileDescriptor commChannel)
public static ParcelFileDescriptor open(File file, int mode) throws FileNotFoundException
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.parseMode(String)
public static ParcelFileDescriptor open(File file, int mode, Handler handler, ParcelFileDescriptor.OnCloseListener listener) throws IOException
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
parseMode(String)
public static ParcelFileDescriptor fromFd(FileDescriptor fd, Handler handler, ParcelFileDescriptor.OnCloseListener listener) throws IOException
IOException
public static ParcelFileDescriptor dup(FileDescriptor orig) throws IOException
IOException
public ParcelFileDescriptor dup() throws IOException
IOException
public static ParcelFileDescriptor fromFd(int fd) throws IOException
fd
- The native fd that the ParcelFileDescriptor should dup.IOException
public static ParcelFileDescriptor adoptFd(int fd)
fd
- The native fd that the ParcelFileDescriptor should adopt.public static ParcelFileDescriptor fromSocket(Socket socket)
socket
- The Socket whose FileDescriptor is used to create
a new ParcelFileDescriptor.public static ParcelFileDescriptor fromDatagramSocket(DatagramSocket datagramSocket)
datagramSocket
- The DatagramSocket whose FileDescriptor is used
to create a new ParcelFileDescriptor.public static ParcelFileDescriptor[] createPipe() throws IOException
IOException
public static ParcelFileDescriptor[] createReliablePipe() throws IOException
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
public static ParcelFileDescriptor[] createSocketPair() throws IOException
IOException
public static ParcelFileDescriptor[] createSocketPair(int type) throws IOException
IOException
public static ParcelFileDescriptor[] createReliableSocketPair() throws IOException
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
public static ParcelFileDescriptor[] createReliableSocketPair(int type) throws IOException
IOException
@Deprecated public static ParcelFileDescriptor fromData(byte[] data, String name) throws IOException
data
- Data to copy.name
- Name for the shared memory area that may back the file descriptor.
This is purely informative and may be null
.IOException
- if there is an error while creating the shared memory area.public static int parseMode(String mode)
open(java.io.File, int)
.
mode
- The string representation of the file mode.IllegalArgumentException
- if the given string does not match a known file mode.public FileDescriptor getFileDescriptor()
public long getStatSize()
stat()
. Returns -1 if the fd is not a file.public long seekTo(long pos) throws IOException
IOException
public int getFd()
public int detachFd()
You should not detach when the original creator of the descriptor is
expecting a reliable signal through close()
or
closeWithError(String)
.
canDetectErrors()
public void close() throws IOException
close
in interface Closeable
close
in interface AutoCloseable
IOException
- If an error occurs attempting to close this ParcelFileDescriptor.public void closeWithError(String msg) throws IOException
msg
- describing the error; must not be null.IOException
public void releaseResources()
public boolean canDetectErrors()
checkError()
public void checkError() throws IOException
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)
.canDetectErrors()
public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
protected void finalize() throws Throwable
Object
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 JavaTM 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.
public int describeContents()
Parcelable
Parcelable.writeToParcel(Parcel, int)
,
the return value of this method must include the
Parcelable.CONTENTS_FILE_DESCRIPTOR
bit.describeContents
in interface Parcelable
Parcelable.CONTENTS_FILE_DESCRIPTOR
public void writeToParcel(Parcel out, int flags)
Parcelable.PARCELABLE_WRITE_RETURN_VALUE
is set in flags,
the file descriptor will be closed after a copy is written to the Parcel.writeToParcel
in interface Parcelable
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.PARCELABLE_WRITE_RETURN_VALUE
.