git.sesse.net Git - ffmpeg/blob - libavcodec/ffjni.h

   1 /*
   2  * JNI utility functions
   3  *
   4  * Copyright (c) 2015-2016 Matthieu Bouron <matthieu.bouron stupeflix.com>
   5  *
   6  * This file is part of FFmpeg.
   7  *
   8  * FFmpeg is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * FFmpeg is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with FFmpeg; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  21  */
  22
  23 #ifndef AVCODEC_FFJNI_H
  24 #define AVCODEC_FFJNI_H
  25
  26 #include <jni.h>
  27
  28 /*
  29  * Attach a JNI environment to the current thread.
  30  *
  31  * @param attached pointer to an integer that will be set to 1 if the
  32  * environment has been attached to the current thread or 0 if it is
  33  * already attached.
  34  * @param log_ctx context used for logging, can be NULL
  35  * @return the JNI environment on success, NULL otherwise
  36  */
  37 JNIEnv *ff_jni_attach_env(int *attached, void *log_ctx);
  38
  39 /*
  40  * Detach the JNI environment from the current thread.
  41  *
  42  * @param log_ctx context used for logging, can be NULL
  43  * @return 0 on success, < 0 otherwise
  44  */
  45 int ff_jni_detach_env(void *log_ctx);
  46
  47 /*
  48  * Convert a jstring to its utf characters equivalent.
  49  *
  50  * @param env JNI environment
  51  * @param string Java string to convert
  52  * @param log_ctx context used for logging, can be NULL
  53  * @return a pointer to an array of unicode characters on success, NULL
  54  * otherwise
  55  */
  56 char *ff_jni_jstring_to_utf_chars(JNIEnv *env, jstring string, void *log_ctx);
  57
  58 /*
  59  * Convert utf chars to its jstring equivalent.
  60  *
  61  * @param env JNI environment
  62  * @param utf_chars a pointer to an array of unicode characters
  63  * @param log_ctx context used for logging, can be NULL
  64  * @return a Java string object on success, NULL otherwise
  65  */
  66 jstring ff_jni_utf_chars_to_jstring(JNIEnv *env, const char *utf_chars, void *log_ctx);
  67
  68 /*
  69  * Extract the error summary from a jthrowable in the form of "className: errorMessage"
  70  *
  71  * @param env JNI environment
  72  * @param exception exception to get the summary from
  73  * @param error address pointing to the error, the value is updated if a
  74  * summary can be extracted
  75  * @param log_ctx context used for logging, can be NULL
  76  * @return 0 on success, < 0 otherwise
  77  */
  78 int ff_jni_exception_get_summary(JNIEnv *env, jthrowable exception, char **error, void *log_ctx);
  79
  80 /*
  81  * Check if an exception has occurred,log it using av_log and clear it.
  82  *
  83  * @param env JNI environment
  84  * @param log value used to enable logging if an exception has occurred,
  85  * 0 disables logging, != 0 enables logging
  86  * @param log_ctx context used for logging, can be NULL
  87  */
  88 int ff_jni_exception_check(JNIEnv *env, int log, void *log_ctx);
  89
  90 /*
  91  * Jni field type.
  92  */
  93 enum FFJniFieldType {
  94
  95     FF_JNI_CLASS,
  96     FF_JNI_FIELD,
  97     FF_JNI_STATIC_FIELD,
  98     FF_JNI_METHOD,
  99     FF_JNI_STATIC_METHOD
 100
 101 };
 102
 103 /*
 104  * Jni field describing a class, a field or a method to be retrieved using
 105  * the ff_jni_init_jfields method.
 106  */
 107 struct FFJniField {
 108
 109     const char *name;
 110     const char *method;
 111     const char *signature;
 112     enum FFJniFieldType type;
 113     int offset;
 114     int mandatory;
 115
 116 };
 117
 118 /*
 119  * Retrieve class references, field ids and method ids to an arbitrary structure.
 120  *
 121  * @param env JNI environment
 122  * @param jfields a pointer to an arbitrary structure where the different
 123  * fields are declared and where the FFJNIField mapping table offsets are
 124  * pointing to
 125  * @param jfields_mapping null terminated array of FFJNIFields describing
 126  * the class/field/method to be retrieved
 127  * @param global make the classes references global. It is the caller
 128  * responsibility to properly release global references.
 129  * @param log_ctx context used for logging, can be NULL
 130  * @return 0 on success, < 0 otherwise
 131  */
 132 int ff_jni_init_jfields(JNIEnv *env, void *jfields, const struct FFJniField *jfields_mapping, int global, void *log_ctx);
 133
 134 /*
 135  * Delete class references, field ids and method ids of an arbitrary structure.
 136  *
 137  * @param env JNI environment
 138  * @param jfields a pointer to an arbitrary structure where the different
 139  * fields are declared and where the FFJNIField mapping table offsets are
 140  * pointing to
 141  * @param jfields_mapping null terminated array of FFJNIFields describing
 142  * the class/field/method to be deleted
 143  * @param global threat the classes references as global and delete them
 144  * accordingly
 145  * @param log_ctx context used for logging, can be NULL
 146  * @return 0 on success, < 0 otherwise
 147  */
 148 int ff_jni_reset_jfields(JNIEnv *env, void *jfields, const struct FFJniField *jfields_mapping, int global, void *log_ctx);
 149
 150 #endif /* AVCODEC_FFJNI_H */