001/*******************************************************************************
002 * Copyright (c) 2024, 2026, Olivier Ayache.  All rights reserved.
003 *
004 * This file is part of AVPKit.
005 *
006 * AVPKit is free software: you can redistribute it and/or modify
007 * it under the terms of the GNU Lesser General Public License as published by
008 * the Free Software Foundation, either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * AVPKit is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with AVPKit.  If not, see <http://www.gnu.org/licenses/>.
018 *******************************************************************************/
019
020package com.avpkit.ferry;
021
022/**
023 * 
024 * Internal Only.
025 * 
026 * An Opaque handle that holds a Native mPointer/handle.
027 * 
028 * This class holds a opaque long value that can be used to pass into JNI C
029 * function that expect a ** in C.
030 * <p>
031 * For example, a function like this in native code:
032 * </p>
033 * <code>
034 * <pre>
035 *   int url_open(URLContext **handlePtr, char *name, int flags);
036 *   int url_read(URLContext *handle, void* buf, int len);
037 * </pre>
038 * </code> might map to the following Java method: <code>
039 * <pre>
040 * public class Example {
041 *   public native int url_open(JNIPointerReference p, String name, int flags);
042 *   public native int url_read(JNIPointerReference p, byte[] buf, int len);
043 *   public void example() {
044 *      int retval = 0;
045 *      JNIPointerReference p;
046 *      // p.setPointer is called by the native function 
047 *      retval = url_open(p, "foo", 0);
048 *      
049 *      // p.getPointer is called by the native function
050 *      byte[] buf = new bytes[1024];
051 *      retval = url_read(p, buf, buf.length);
052 *   }
053 * </pre>
054 * </code>
055 * 
056 * <p>
057 * <b>IMPORTANT: DO NOT RENAME THIS CLASS OR METHODS IN IT. NATIVE CODE DEPENDS
058 * ON THE NAMES AND SIGNATURES.</b>
059 * </p>
060 * 
061 */
062public class JNIPointerReference
063{
064  private long mPointer;
065
066  /**
067   * Internal Only.
068   */
069  public JNIPointerReference()
070  {
071    mPointer = -1;
072  }
073  
074  @SuppressWarnings("unused")
075  // This method is "private" but we assume it'll be called from
076  // native code (that can override protections).
077  private synchronized long getPointer()
078  {
079    return mPointer;
080  }
081
082  // This method is "private" but we assume it'll be called from
083  // native code (that can override protections).
084  @SuppressWarnings("unused")
085  private synchronized long setPointer(long newVal)
086  {
087    long oldVal = mPointer;
088    mPointer = newVal;
089    return oldVal;
090  }
091
092  /**
093   * Internal Only.
094   */
095  public String toString()
096  {
097    return "native:" + mPointer;
098  }
099}