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 #if !defined(__BIONIC__) && !defined(__INTRODUCED_IN)
33 #define __INTRODUCED_IN(x)
34 #endif
35 
36 __BEGIN_DECLS
37 
38 /**
39  * Returns a new java.io.FileDescriptor.
40  *
41  * The FileDescriptor created represents an invalid Unix file descriptor (represented by
42  * a file descriptor value of -1).
43  *
44  * Callers of this method should be aware that it can fail, returning NULL with a pending Java
45  * exception.
46  *
47  * Available since API level 31.
48  *
49  * \param env a pointer to the JNI Native Interface of the current thread.
50  * \return a java.io.FileDescriptor on success, nullptr if insufficient heap memory is available.
51  */
52 jobject AFileDescriptor_create(JNIEnv* env) __INTRODUCED_IN(31);
53 
54 /**
55  * Returns the Unix file descriptor represented by the given java.io.FileDescriptor.
56  *
57  * A return value of -1 indicates that \a fileDescriptor represents an invalid file descriptor.
58  *
59  * Aborts the program if \a fileDescriptor is not a java.io.FileDescriptor instance.
60  *
61  * Available since API level 31.
62  *
63  * \param env a pointer to the JNI Native Interface of the current thread.
64  * \param fileDescriptor a java.io.FileDescriptor instance.
65  * \return the Unix file descriptor wrapped by \a fileDescriptor.
66  */
67 int AFileDescriptor_getFd(JNIEnv* env, jobject fileDescriptor) __INTRODUCED_IN(31);
68 
69 /**
70  * Sets the Unix file descriptor represented by the given java.io.FileDescriptor.
71  *
72  * This function performs no validation of the Unix file descriptor argument, \a fd. Android uses
73  * the value -1 to represent an invalid file descriptor, all other values are considered valid.
74  * The validity of a file descriptor can be checked with FileDescriptor#valid().
75  *
76  * Aborts the program if \a fileDescriptor is not a java.io.FileDescriptor instance.
77  *
78  * Available since API level 31.
79  *
80  * \param env a pointer to the JNI Native Interface of the current thread.
81  * \param fileDescriptor a java.io.FileDescriptor instance.
82  * \param fd a Unix file descriptor that \a fileDescriptor will subsequently represent.
83  */
84 void AFileDescriptor_setFd(JNIEnv* env, jobject fileDescriptor, int fd) __INTRODUCED_IN(31);
85 
86 __END_DECLS
87 
88 /** @} */
89