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 permanently a JNI environment to the current thread and retrieve it.
  30  *
  31  * If successfully attached, the JNI environment will automatically be detached
  32  * at thread destruction.
  33  *
  34  * @param attached pointer to an integer that will be set to 1 if the
  35  * environment has been attached to the current thread or 0 if it is
  36  * already attached.
  37  * @param log_ctx context used for logging, can be NULL
  38  * @return the JNI environment on success, NULL otherwise
  39  */
  40 JNIEnv *ff_jni_get_env(void *log_ctx);
  41
  42 /*
  43  * Convert a jstring to its utf characters equivalent.
  44  *
  45  * @param env JNI environment
  46  * @param string Java string to convert
  47  * @param log_ctx context used for logging, can be NULL
  48  * @return a pointer to an array of unicode characters on success, NULL
  49  * otherwise
  50  */
  51 char *ff_jni_jstring_to_utf_chars(JNIEnv *env, jstring string, void *log_ctx);
  52
  53 /*
  54  * Convert utf chars to its jstring equivalent.
  55  *
  56  * @param env JNI environment
  57  * @param utf_chars a pointer to an array of unicode characters
  58  * @param log_ctx context used for logging, can be NULL
  59  * @return a Java string object on success, NULL otherwise
  60  */
  61 jstring ff_jni_utf_chars_to_jstring(JNIEnv *env, const char *utf_chars, void *log_ctx);
  62
  63 /*
  64  * Extract the error summary from a jthrowable in the form of "className: errorMessage"
  65  *
  66  * @param env JNI environment
  67  * @param exception exception to get the summary from
  68  * @param error address pointing to the error, the value is updated if a
  69  * summary can be extracted
  70  * @param log_ctx context used for logging, can be NULL
  71  * @return 0 on success, < 0 otherwise
  72  */
  73 int ff_jni_exception_get_summary(JNIEnv *env, jthrowable exception, char **error, void *log_ctx);
  74
  75 /*
  76  * Check if an exception has occurred,log it using av_log and clear it.
  77  *
  78  * @param env JNI environment
  79  * @param log value used to enable logging if an exception has occurred,
  80  * 0 disables logging, != 0 enables logging
  81  * @param log_ctx context used for logging, can be NULL
  82  */
  83 int ff_jni_exception_check(JNIEnv *env, int log, void *log_ctx);
  84
  85 /*
  86  * Jni field type.
  87  */
  88 enum FFJniFieldType {
  89
  90     FF_JNI_CLASS,
  91     FF_JNI_FIELD,
  92     FF_JNI_STATIC_FIELD,
  93     FF_JNI_METHOD,
  94     FF_JNI_STATIC_METHOD
  95
  96 };
  97
  98 /*
  99  * Jni field describing a class, a field or a method to be retrieved using
 100  * the ff_jni_init_jfields method.
 101  */
 102 struct FFJniField {
 103
 104     const char *name;
 105     const char *method;
 106     const char *signature;
 107     enum FFJniFieldType type;
 108     int offset;
 109     int mandatory;
 110
 111 };
 112
 113 /*
 114  * Retrieve class references, field ids and method ids to an arbitrary structure.
 115  *
 116  * @param env JNI environment
 117  * @param jfields a pointer to an arbitrary structure where the different
 118  * fields are declared and where the FFJNIField mapping table offsets are
 119  * pointing to
 120  * @param jfields_mapping null terminated array of FFJNIFields describing
 121  * the class/field/method to be retrieved
 122  * @param global make the classes references global. It is the caller
 123  * responsibility to properly release global references.
 124  * @param log_ctx context used for logging, can be NULL
 125  * @return 0 on success, < 0 otherwise
 126  */
 127 int ff_jni_init_jfields(JNIEnv *env, void *jfields, const struct FFJniField *jfields_mapping, int global, void *log_ctx);
 128
 129 /*
 130  * Delete class references, field ids and method ids of an arbitrary structure.
 131  *
 132  * @param env JNI environment
 133  * @param jfields a pointer to an arbitrary structure where the different
 134  * fields are declared and where the FFJNIField mapping table offsets are
 135  * pointing to
 136  * @param jfields_mapping null terminated array of FFJNIFields describing
 137  * the class/field/method to be deleted
 138  * @param global threat the classes references as global and delete them
 139  * accordingly
 140  * @param log_ctx context used for logging, can be NULL
 141  * @return 0 on success, < 0 otherwise
 142  */
 143 int ff_jni_reset_jfields(JNIEnv *env, void *jfields, const struct FFJniField *jfields_mapping, int global, void *log_ctx);
 144
 145 #endif /* AVCODEC_FFJNI_H */