org.freedesktop.gstreamer.glib

Class Natives

java.lang.Object

org.freedesktop.gstreamer.glib.Natives

public final class Natives
extends Object

Here be Dragons!

This class provides utility functions for working with the underlying native bindings, creating NativeObject from pointers and extracting native pointers from NativeObjects. It should normally only be necessary to make use of these methods if extending the bindings externally or interacting with other native code.

Method Summary

Modifier and Type	Method and Description
static <T extends NativeObject> T	callerOwnsReturn(org.freedesktop.gstreamer.lowlevel.GPointer ptr, Class<T> cls) Get a NativeObject instance of the requested type for the provided Pointer, for use with native functions returning Transfer Full or Transfer Floating results.
static <T extends NativeObject> T	callerOwnsReturn(com.sun.jna.Pointer ptr, Class<T> cls) Get a NativeObject instance of the requested type for the provided Pointer, for use with native functions returning Transfer Full or Transfer Floating results.
static org.freedesktop.gstreamer.lowlevel.GPointer	getPointer(NativeObject obj) Get the underlying native typed GPointer for a NativeObject.
static com.sun.jna.Pointer	getRawPointer(NativeObject obj) Get the underlying raw native Pointer for a NativeObject.
static NativeObject.Initializer	initializer(com.sun.jna.Pointer ptr) Create a NativeObject.Initializer for the provided Pointer.
static NativeObject.Initializer	initializer(com.sun.jna.Pointer ptr, boolean needRef) Create a NativeObject.Initializer for the provided Pointer.
static NativeObject.Initializer	initializer(com.sun.jna.Pointer ptr, boolean needRef, boolean ownsHandle) Create a NativeObject.Initializer for the provided Pointer.
static <T extends NativeObject> T	objectFor(org.freedesktop.gstreamer.lowlevel.GPointer ptr, Class<T> cls, boolean needRef, boolean ownsHandle) Get a NativeObject instance of the requested type for the provided Pointer.
static <T extends NativeObject> T	objectFor(com.sun.jna.Pointer ptr, Class<T> cls, boolean needRef, boolean ownsHandle) Get a NativeObject instance of the requested type for the provided Pointer.
static boolean	ownsReference(NativeObject obj) Return whether underlying native pointer is owned by this object.
static <T extends RefCountedObject> T	ref(T obj) Increase the reference count of a RefCountedObject
static <T extends NativeObject> NativeObject.TypeRegistration<T>	registration(Class<T> javaType, String gTypeName, Function<NativeObject.Initializer,? extends T> factory) Create a NativeObject.TypeRegistration for linking NativeObject subclasses to GTypes.
static <T extends RefCountedObject> T	unref(T obj) Decrease the reference count of a RefCountedObject
static boolean	validReference(NativeObject obj) Returns whether this object is valid or not.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

initializer

public static final NativeObject.Initializer initializer(com.sun.jna.Pointer ptr)

Create a NativeObject.Initializer for the provided Pointer.

This initializer will own the handle.

This initializer will not request a ref increase (only relevant if used with instance of RefCountedObject)

Parameters:

ptr - native pointer

Returns:

initializer

initializer

public static final NativeObject.Initializer initializer(com.sun.jna.Pointer ptr,
                                                         boolean needRef)

Create a NativeObject.Initializer for the provided Pointer.

This initializer will own the handle.

Parameters:

ptr - native pointer

needRef - whether to request a ref increase (only relevant if used with instance of RefCountedObject)

Returns:

initializer

initializer

public static final NativeObject.Initializer initializer(com.sun.jna.Pointer ptr,
                                                         boolean needRef,
                                                         boolean ownsHandle)

Create a NativeObject.Initializer for the provided Pointer.

Parameters:

ptr - native pointer

needRef - whether to request a ref increase (only relevant if used with instance of RefCountedObject)

ownsHandle - whether the NativeObject will own the handle, and should dispose of the native resource when GC'd or explicitly disposed.

Returns:

initializer

objectFor

public static <T extends NativeObject> T objectFor(com.sun.jna.Pointer ptr,
                                                   Class<T> cls,
                                                   boolean needRef,
                                                   boolean ownsHandle)

Get a NativeObject instance of the requested type for the provided Pointer. Will return a cached instance if one already exists.

Type Parameters:

T - NativeObject type to return

Parameters:

ptr - native Pointer

cls - Class of type T

needRef - whether to request a ref increase (only relevant if T is subclass of RefCountedObject)

ownsHandle - whether the NativeObject will own the handle, and should dispose of the native resource when GC'd or explicitly disposed.

Returns:

native object of type T

objectFor

public static <T extends NativeObject> T objectFor(org.freedesktop.gstreamer.lowlevel.GPointer ptr,
                                                   Class<T> cls,
                                                   boolean needRef,
                                                   boolean ownsHandle)

Get a NativeObject instance of the requested type for the provided Pointer. Will return a cached instance if one already exists.

Type Parameters:

T - NativeObject type to return

Parameters:

ptr - native Pointer

cls - Class of type T

needRef - whether to request a ref increase (only relevant if T is subclass of RefCountedObject)

ownsHandle - whether the NativeObject will own the handle, and should dispose of the native resource when GC'd or explicitly disposed.

Returns:

native object of type T

callerOwnsReturn

public static <T extends NativeObject> T callerOwnsReturn(com.sun.jna.Pointer ptr,
                                                          Class<T> cls)

Get a NativeObject instance of the requested type for the provided Pointer, for use with native functions returning Transfer Full or Transfer Floating results.

This method will return a cached instance if one already exists. If the cached instance is a RefCountedObject this method will release a reference.

Type Parameters:

T - NativeObject type to return

Parameters:

ptr - native Pointer

cls - Class of type T

Returns:

native object of type T

callerOwnsReturn

public static <T extends NativeObject> T callerOwnsReturn(org.freedesktop.gstreamer.lowlevel.GPointer ptr,
                                                          Class<T> cls)

Get a NativeObject instance of the requested type for the provided Pointer, for use with native functions returning Transfer Full or Transfer Floating results.

This method will return a cached instance if one already exists. If the cached instance is a RefCountedObject this method will release a reference.

Type Parameters:

T - NativeObject type to return

Parameters:

ptr - native Pointer

cls - Class of type T

Returns:

native object of type T

getRawPointer

public static com.sun.jna.Pointer getRawPointer(NativeObject obj)

Get the underlying raw native Pointer for a NativeObject.

Parameters:

obj - native object

Returns:

native pointer

Throws:

IllegalStateException - if the native reference has been invalidated or disposed

getPointer

public static org.freedesktop.gstreamer.lowlevel.GPointer getPointer(NativeObject obj)

Get the underlying native typed GPointer for a NativeObject.

Parameters:

obj - native object

Returns:

native typed pointer

Throws:

IllegalStateException - if the native reference has been invalidated or disposed

ownsReference

public static boolean ownsReference(NativeObject obj)

Return whether underlying native pointer is owned by this object.

Parameters:

obj - native object which may hold a reference to native pointer

Returns:

whether underlying native pointer is owned by this object

validReference

public static boolean validReference(NativeObject obj)

Returns whether this object is valid or not.

Parameters:

obj - native object

Returns:

whether this object is valid or not

ref

public static <T extends RefCountedObject> T ref(T obj)

Increase the reference count of a RefCountedObject

Type Parameters:

T - type of object

Parameters:

obj - object to increase reference count on

Returns:

object

unref

public static <T extends RefCountedObject> T unref(T obj)

Decrease the reference count of a RefCountedObject

Type Parameters:

T - type of object

Parameters:

obj - object to decrease reference count on

Returns:

object

registration

public static <T extends NativeObject> NativeObject.TypeRegistration<T> registration(Class<T> javaType,
                                                                                     String gTypeName,
                                                                                     Function<NativeObject.Initializer,? extends T> factory)

Create a NativeObject.TypeRegistration for linking NativeObject subclasses to GTypes.

Be careful to respect the link between Java type hierarchy of registered classes and the underlying GType hierarchy. eg. if the GType is a subclass of GObject then the Java type must extend from GObject

The factory function should normally be a constructor reference.

Registrations can be provided externally using NativeObject.TypeProvider instances registered for use with ServiceLoader

Type Parameters:

T - Java type

Parameters:

javaType - Java type class

gTypeName - name of the GType

factory - a factory function to return an instance of T given a NativeObject.Initializer. Normally a constructor reference - T::new

Returns:

registration