1 /*
2  * Copyright (C) 2020 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /**
18  * @addtogroup FileDescriptor File Descriptor
19  * @{
20  */
21 
22 /**
23  * @file file_descriptor_jni.h
24  */
25 
26 #pragma once
27 
28 #include <sys/cdefs.h>
29 
30 #include <jni.h>
31 
32 __BEGIN_DECLS
33 
34 #if __ANDROID_API__ >= __ANDROID_API_S__
35 
36 /**
37  * Returns a new java.io.FileDescriptor.
38  *
39  * The FileDescriptor created represents an invalid Unix file descriptor (represented by
40  * a file descriptor value of -1).
41  *
42  * Callers of this method should be aware that it can fail, returning NULL with a pending Java
43  * exception.
44  *
45  * Available since API level 31.
46  *
47  * \param env a pointer to the JNI Native Interface of the current thread.
48  * \return a java.io.FileDescriptor on success, nullptr if insufficient heap memory is available.
49  */
50 jobject AFileDescriptor_create(JNIEnv* env) __INTRODUCED_IN(31);
51 
52 /**
53  * Returns the Unix file descriptor represented by the given java.io.FileDescriptor.
54  *
55  * A return value of -1 indicates that \a fileDescriptor represents an invalid file descriptor.
56  *
57  * Aborts the program if \a fileDescriptor is not a java.io.FileDescriptor instance.
58  *
59  * Available since API level 31.
60  *
61  * \param env a pointer to the JNI Native Interface of the current thread.
62  * \param fileDescriptor a java.io.FileDescriptor instance.
63  * \return the Unix file descriptor wrapped by \a fileDescriptor.
64  */
65 int AFileDescriptor_getFD(JNIEnv* env, jobject fileDescriptor) __INTRODUCED_IN(31);
66 
67 /**
68  * Sets the Unix file descriptor represented by the given java.io.FileDescriptor.
69  *
70  * This function performs no validation of the Unix file descriptor argument, \a fd. Android uses
71  * the value -1 to represent an invalid file descriptor, all other values are considered valid.
72  * The validity of a file descriptor can be checked with FileDescriptor#valid().
73  *
74  * Aborts the program if \a fileDescriptor is not a java.io.FileDescriptor instance.
75  *
76  * Available since API level 31.
77  *
78  * \param env a pointer to the JNI Native Interface of the current thread.
79  * \param fileDescriptor a java.io.FileDescriptor instance.
80  * \param fd a Unix file descriptor that \a fileDescriptor will subsequently represent.
81  */
82 void AFileDescriptor_setFD(JNIEnv* env, jobject fileDescriptor, int fd) __INTRODUCED_IN(31);
83 
84 #endif  // __ANDROID_API__ >= 31
85 
86 __END_DECLS
87 
88 /** @} */
89