Module javaobjectivecbridge
Package ca.weblite.objc

Class RuntimeUtils

java.lang.Object
ca.weblite.objc.RuntimeUtils
public class RuntimeUtils extends Object
A Java class with static methods that interact with the Objective-C runtime. These methods wrap the *very* low level methods provided by the Runtime class to provide a slightly higher level of abstraction.

It is helpful to perform a static import of the methods in this class if you will be using the objc runtime library, as it contains many utility methods to deal with Objective-C primitives. E.g. the cls() method can return the Pointer to a class given its name. The clsName() returns the name of the class specified by a Pointer().

There are also many variants of the msg() method for sendng messages to objects in the Objective-C runtime.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static com.sun.jna.Pointer
    addr(Peerable peer)
    Returns the pointer to the Native peer for a Peerable object.
    static int
    arraySize(String signature)
    Returns the size of an array that is specified in a signature.
    static com.sun.jna.Pointer
    cls(Peerable peer)
    Returns a pointer to a class given a Peerable object which wraps the pointer.
    static com.sun.jna.Pointer
    cls(String name)
    Returns a pointer to the class for specific class name.
    static String
    clsName(Peerable peer)
    A wrapper for the clsName() method given a Peerable object that wraps the class pointer.
    static String
    clsName(com.sun.jna.Pointer cls)
    Returns the name of an objective C class specified by the given class pointer.
    static long
    createProxy(Recipient client)
    Registers a Java object with the Objective-C runtime so that it can begin to receive messages from it.
    static com.sun.jna.Pointer
    getAsReference(Object val, String signature)
    Wraps the given value in the appropriate ByReference subclass according to the provided signature.
    static com.sun.jna.ptr.ByReference
    getAsReferenceWrapper(Object val, String signature)
    Wraps the given value in the appropriate ByReference subclass according to the provided signature.
    static Recipient
    getJavaPeer(long nsObject)
    Returns the Java peer recipient for a native Objective-C object if it exists.
    static Object
    msg(boolean coerceReturn, boolean coerceArgs, com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
    Sends a message with the option of coercing the inputs and outputs.
    static Object
    msg(Message... messages)
    Sends a batch of messages in sequence.
    static long
    msg(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
    Sends a message to a specified class using the given selector.
    static long
    msg(com.sun.jna.Pointer receiver, String msg, Object... args)
    Sends a message to a specified class using the given selector.
    static long
    msg(String cls, com.sun.jna.Pointer msg, Object... args)
    Sends a message to a specified class using the given selector.
    static long
    msg(String cls, String msg, Object... args)
    Sends a message to a specified class using the given selector.
    static boolean
    msgBoolean(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
    Wrapper around msg() that returns a boolean value.
    static boolean
    msgBoolean(com.sun.jna.Pointer receiver, String selector, Object... args)
    Wrapper around msg() that returns a boolean value.
    static boolean
    msgBoolean(String receiver, com.sun.jna.Pointer selector, Object... args)
    Wrapper around msg() that returns a boolean value.
    static boolean
    msgBoolean(String receiver, String selector, Object... args)
    Wrapper around msg() that returns a boolean value.
    static double
    msgDouble(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
    Sends a message that returns a double value.
    static double
    msgDouble(com.sun.jna.Pointer receiver, String selector, Object... args)
    Sends a message that returns a double value.
    static double
    msgDouble(String receiver, com.sun.jna.Pointer selector, Object... args)
    Sends a message that returns a double value.
    static double
    msgDouble(String receiver, String selector, Object... args)
    Sends a message that returns a double value.
    static int
    msgInt(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
    Wrapper around msg() that returns an int.
    static int
    msgInt(com.sun.jna.Pointer receiver, String selector, Object... args)
    Wrapper around msg() that returns an int.
    static int
    msgInt(String receiver, com.sun.jna.Pointer selector, Object... args)
    Wrapper around msg() that returns an int.
    static int
    msgInt(String receiver, String selector, Object... args)
    Wrapper around msg() that returns an int.
    static com.sun.jna.Pointer
    msgPointer(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
    Wrapper around msg() that returns a Pointer.
    static com.sun.jna.Pointer
    msgPointer(com.sun.jna.Pointer receiver, String selector, Object... args)
    Wrapper around msg() that returns a Pointer.
    static com.sun.jna.Pointer
    msgPointer(String receiver, com.sun.jna.Pointer selector, Object... args)
    Wrapper around msg() that returns a Pointer.
    static com.sun.jna.Pointer
    msgPointer(String receiver, String selector, Object... args)
    Wrapper around msg() that returns a Pointer.
    static String
    msgString(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
    Wrapper around msg() that returns a string value.
    static String
    msgString(com.sun.jna.Pointer receiver, String selector, Object... args)
    Wrapper around msg() that returns a string value.
    static String
    msgString(String receiver, com.sun.jna.Pointer selector, Object... args)
    Wrapper around msg() that returns a string value.
    static String
    msgString(String receiver, String selector, Object... args)
    Wrapper around msg() that returns a string value.
    static com.sun.jna.Pointer
    sel(Peerable peer)
    Returns a pointer to the selector that is wrapped by a Peerable object.
    static com.sun.jna.Pointer
    sel(String name)
    Returns a pointer to the selector specified by the given selector name.
    static String
    selName(Peerable peer)
    Returns the name of a selector.
    static String
    selName(com.sun.jna.Pointer sel)
    Returns the name of a selector.
    static String
    str(com.sun.jna.Pointer str)
    Converts A native NSString object to a Java string.
    static com.sun.jna.Pointer
    str(String str)
    Converts a Java string to an NSString object.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • cls

      public static com.sun.jna.Pointer cls(String name)
      Returns a pointer to the class for specific class name. 
       
 Pointer nsObject = cls("NSObject");
      Parameters:
      name - The name of the class to retrieve.
      Returns:
      The pointer to the class structure.

    • cls

      public static com.sun.jna.Pointer cls(Peerable peer)
      Returns a pointer to a class given a Peerable object which wraps the pointer. Effectively this just calls peer.getPeer() and returns its value. A convenience method.
      Parameters:
      peer - The peer object that is wrapping the Objective-C class object.
      Returns:
      A Pointer to the Objective-C class.

    • clsName

      public static String clsName(com.sun.jna.Pointer cls)
      Returns the name of an objective C class specified by the given class pointer.
      Parameters:
      cls - The pointer to the class whose name we wish to retrieve.
      Returns:
      The name of the class.
      See Also:

    • clsName

      public static String clsName(Peerable peer)
      A wrapper for the clsName() method given a Peerable object that wraps the class pointer. This will return the class name.
      Parameters:
      peer - a Peerable object.
      Returns:
      a String object.
      See Also:

    • sel

      public static com.sun.jna.Pointer sel(String name)
      Returns a pointer to the selector specified by the given selector name.
      Parameters:
      name - a String object.
      Returns:
      Pointer to an Objective-C message selector.
      See Also:

    • sel

      public static com.sun.jna.Pointer sel(Peerable peer)
      Returns a pointer to the selector that is wrapped by a Peerable object.
      Parameters:
      peer - a Peerable object.
      Returns:
      Pointer to a specified selector.

    • selName

      public static String selName(com.sun.jna.Pointer sel)
      Returns the name of a selector.
      Parameters:
      sel - Pointer to a selector.
      Returns:
      The name of the selector.

    • selName

      public static String selName(Peerable peer)
      Returns the name of a selector.
      Parameters:
      peer - a Peerable object.
      Returns:
      The name of the selector.

    • msg

      public static long msg(String cls, String msg, Object... args)
      Sends a message to a specified class using the given selector.
      Parameters:
      cls - The name of the class.
      msg - The name of the selector.
      args - The arguments passed to the method. These are passed raw and will not be coerced.
      Returns:
      The result of the message. This may be a pointer, if the message returns a pointer, or a value, if the method returns a BOOL, long, int, short, byte, or char. Note that you cannot use this method for messages that return float and double values. For these, you must use msgDouble(). This is because doubles and floats are handled using a different underlying runtime function (objc_msgSend_fpret). Alternatively you can use the variation of msg() that takes coerceInput and coerceOutput boolean values, as this will automatically choose the correct underlying message function depending on the return type reported by the message signature.
      See Also:

    • msg

      public static long msg(String cls, com.sun.jna.Pointer msg, Object... args)
      Sends a message to a specified class using the given selector.
      Parameters:
      cls - The name of the class.
      msg - The name of the selector.
      args - The arguments passed to the method. These are passed raw and will not be coerced.
      Returns:
      The result of the message. This may be a pointer, if the message returns a pointer, or a value, if the method returns a BOOL, long, int, short, byte, or char. Note that you cannot use this method for messages that return float and double values. For these, you must use msgDouble(). This is because doubles and floats are handled using a different underlying runtime function (objc_msgSend_fpret). Alternatively you can use the variation of msg() that takes coerceInput and coerceOutput boolean values, as this will automatically choose the correct underlying message function depending on the return type reported by the message signature.
      See Also:

    • msg

      public static long msg(com.sun.jna.Pointer receiver, String msg, Object... args)
      Sends a message to a specified class using the given selector.
      Parameters:
      msg - The name of the selector.
      args - The arguments passed to the method. These are passed raw and will not be coerced.
      receiver - a Pointer object.
      Returns:
      The result of the message. This may be a pointer, if the message returns a pointer, or a value, if the method returns a BOOL, long, int, short, byte, or char. Note that you cannot use this method for messages that return float and double values. For these, you must use msgDouble(). This is because doubles and floats are handled using a different underlying runtime function (objc_msgSend_fpret). Alternatively you can use the variation of msg() that takes coerceInput and coerceOutput boolean values, as this will automatically choose the correct underlying message function depending on the return type reported by the message signature.
      See Also:

    • msg

      public static long msg(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      Sends a message to a specified class using the given selector.
      Parameters:
      args - The arguments passed to the method. These are passed raw and will not be coerced.
      receiver - a Pointer object.
      selector - a Pointer object.
      Returns:
      The result of the message. This may be a pointer, if the message returns a pointer, or a value, if the method returns a BOOL, long, int, short, byte, or char. Note that you cannot use this method for messages that return float and double values. For these, you must use msgDouble(). This is because doubles and floats are handled using a different underlying runtime function (objc_msgSend_fpret). Alternatively you can use the variation of msg() that takes coerceInput and coerceOutput boolean values, as this will automatically choose the correct underlying message function depending on the return type reported by the message signature.
      See Also:

    • msgPointer

      public static com.sun.jna.Pointer msgPointer(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      Wrapper around msg() that returns a Pointer. This should only be used for sending messages that return Pointers (or Objects).
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      A Pointer return value of the message.

    • msgPointer

      public static com.sun.jna.Pointer msgPointer(com.sun.jna.Pointer receiver, String selector, Object... args)
      Wrapper around msg() that returns a Pointer. This should only be used for sending messages that return Pointers (or Objects).
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      A Pointer return value of the message.

    • msgPointer

      public static com.sun.jna.Pointer msgPointer(String receiver, com.sun.jna.Pointer selector, Object... args)
      Wrapper around msg() that returns a Pointer. This should only be used for sending messages that return Pointers (or Objects).
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      A Pointer return value of the message.

    • msgPointer

      public static com.sun.jna.Pointer msgPointer(String receiver, String selector, Object... args)
      Wrapper around msg() that returns a Pointer. This should only be used for sending messages that return Pointers (or Objects).
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      A Pointer return value of the message.

    • msgInt

      public static int msgInt(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      Wrapper around msg() that returns an int. This should only be used for sending messages that return int-compatible numeric values. E.g. byte, bool, long, int, short. Do not use this if the message will return something else (like a float, double, string, or pointer). Narrowing primitive conversion will be applied; this will cause information loss if the long result does not fit in the int value range.
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      An int value returned by the message.

    • msgInt

      public static int msgInt(String receiver, com.sun.jna.Pointer selector, Object... args)
      Wrapper around msg() that returns an int. This should only be used for sending messages that return int-compatible numeric values. E.g. byte, bool, long, int, short. Do not use this if the message will return something else (like a float, double, string, or pointer).
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      An int value returned by the message.

    • msgInt

      public static int msgInt(String receiver, String selector, Object... args)
      Wrapper around msg() that returns an int. This should only be used for sending messages that return int-compatible numeric values. E.g. byte, bool, long, int, short. Do not use this if the message will return something else (like a float, double, string, or pointer).
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      An int value returned by the message.

    • msgInt

      public static int msgInt(com.sun.jna.Pointer receiver, String selector, Object... args)
      Wrapper around msg() that returns an int. This should only be used for sending messages that return int-compatible numeric values. E.g. byte, bool, long, int, short. Do not use this if the message will return something else (like a float, double, string, or pointer).
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      An int value returned by the message.

    • msgBoolean

      public static boolean msgBoolean(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      Wrapper around msg() that returns a boolean value. This should only be used for sending messages that return boolean-compatible numeric values. Essentially any non-zero value is interpreted (and returned) as true. Zero values are interpreted as false.
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - Arguments passed to the message.
      Returns:
      Boolean return value of the message.

    • msgBoolean

      public static boolean msgBoolean(String receiver, com.sun.jna.Pointer selector, Object... args)
      Wrapper around msg() that returns a boolean value. This should only be used for sending messages that return boolean-compatible numeric values. Essentially any non-zero value is interpreted (and returned) as true. Zero values are interpreted as false.
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - Arguments passed to the message.
      Returns:
      Boolean return value of the message.

    • msgBoolean

      public static boolean msgBoolean(String receiver, String selector, Object... args)
      Wrapper around msg() that returns a boolean value. This should only be used for sending messages that return boolean-compatible numeric values. Essentially any non-zero value is interpreted (and returned) as true. Zero values are interpreted as false.
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - Arguments passed to the message.
      Returns:
      Boolean return value of the message.

    • msgBoolean

      public static boolean msgBoolean(com.sun.jna.Pointer receiver, String selector, Object... args)
      Wrapper around msg() that returns a boolean value. This should only be used for sending messages that return boolean-compatible numeric values. Essentially any non-zero value is interpreted (and returned) as true. Zero values are interpreted as false.
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - Arguments passed to the message.
      Returns:
      Boolean return value of the message.

    • msgString

      public static String msgString(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      Wrapper around msg() that returns a string value. This should only be used for messages that return a CString. Do not use this for messages that return numeric values or Pointers to objects (e.g. NSString). Use the msg() variant that takes coerceInputs and coerceOutputs parameters if you want NSStrings to be automatically converted to java Strings.
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - Arguments passed to the message.
      Returns:
      The string return value of the message.

    • msgString

      public static String msgString(String receiver, com.sun.jna.Pointer selector, Object... args)
      Wrapper around msg() that returns a string value. This should only be used for messages that return a CString. Do not use this for messages that return numeric values or Pointers to objects (e.g. NSString). Use the msg() variant that takes coerceInputs and coerceOutputs parameters if you want NSStrings to be automatically converted to java Strings.
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - Arguments passed to the message.
      Returns:
      The string return value of the message.

    • msgString

      public static String msgString(String receiver, String selector, Object... args)
      Wrapper around msg() that returns a string value. This should only be used for messages that return a CString. Do not use this for messages that return numeric values or Pointers to objects (e.g. NSString). Use the msg() variant that takes coerceInputs and coerceOutputs parameters if you want NSStrings to be automatically converted to java Strings.
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - Arguments passed to the message.
      Returns:
      The string return value of the message.

    • msgString

      public static String msgString(com.sun.jna.Pointer receiver, String selector, Object... args)
      Wrapper around msg() that returns a string value. This should only be used for messages that return a CString. Do not use this for messages that return numeric values or Pointers to objects (e.g. NSString). Use the msg() variant that takes coerceInputs and coerceOutputs parameters if you want NSStrings to be automatically converted to java Strings.
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - Arguments passed to the message.
      Returns:
      The string return value of the message.

    • msgDouble

      public static double msgDouble(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      Sends a message that returns a double value. This variant must be used if the method returns a float or a double. It doesn't actually wrap the primitive msg() method.. Rather it uses a different core Objective-C method, objc_msgSend_fpret().
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      The double return value of the message

    • msgDouble

      public static double msgDouble(String receiver, com.sun.jna.Pointer selector, Object... args)
      Sends a message that returns a double value. This variant must be used if the method returns a float or a double. It doesn't actually wrap the primitive msg() method.. Rather it uses a different core Objective-C method, objc_msgSend_fpret().
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      The double return value of the message

    • msgDouble

      public static double msgDouble(String receiver, String selector, Object... args)
      Sends a message that returns a double value. This variant must be used if the method returns a float or a double. It doesn't actually wrap the primitive msg() method.. Rather it uses a different core Objective-C method, objc_msgSend_fpret().
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      The double return value of the message

    • msgDouble

      public static double msgDouble(com.sun.jna.Pointer receiver, String selector, Object... args)
      Sends a message that returns a double value. This variant must be used if the method returns a float or a double. It doesn't actually wrap the primitive msg() method.. Rather it uses a different core Objective-C method, objc_msgSend_fpret().
      Parameters:
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments passed to the message.
      Returns:
      The double return value of the message

    • msg

      public static Object msg(boolean coerceReturn, boolean coerceArgs, com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      Sends a message with the option of coercing the inputs and outputs. This variant uses a higher level of abstraction than the standard msg() and msgXXX() methods. If coerceReturn and coerceArgs are set to true, then this method will convert the inputs from Java inputs to the corresponding Objective-C inputs. Further it will return values that are more appropriate for use in Java.

      Furthermore, this variant is smart about which variable of msg() to call behind the scenes. E.g. if the message signature specifies that this message returns a double, it will automatically use the double variant of msg().

      Parameters:
      coerceReturn - If true, then the return value will be mapped to an appropriate Java value using the TypeMapper class.
      coerceArgs - If true, then the inputs will be mapped from Java to appropriate C values using the TypeMapper class.
      receiver - The target of the message.
      selector - The selector for the message.
      args - The arguments to be passed in the message.
      Returns:
      The return value of the message. This may be a Pointer or a value depending on the return type of the message.

    • arraySize

      public static int arraySize(String signature)
      Returns the size of an array that is specified in a signature.
      Parameters:
      signature - The signature for a parameter using Objective-C type encodings.
      Returns:
      The size of the array.
      See Also:

    • addr

      public static com.sun.jna.Pointer addr(Peerable peer)
      Returns the pointer to the Native peer for a Peerable object.
      Parameters:
      peer - a Peerable object.
      Returns:
      The Pointer to a native peer.

    • msg

      public static Object msg(Message... messages)
      Sends a batch of messages in sequence.
      Parameters:
      messages - a Message object.
      Returns:
      a Object object.

    • str

      public static com.sun.jna.Pointer str(String str)
      Converts a Java string to an NSString object.
      Parameters:
      str - The Java string to convert.
      Returns:
      Pointer to the NSString that corresponds to this string.

    • str

      public static String str(com.sun.jna.Pointer str)
      Converts A native NSString object to a Java string.
      Parameters:
      str - a Pointer object.
      Returns:
      A Java string.

    • getAsReference

      public static com.sun.jna.Pointer getAsReference(Object val, String signature)
      Wraps the given value in the appropriate ByReference subclass according to the provided signature. This is a useful method in cases where you need to pass a parameter to a C-function by reference, but you don't necessarily know what type of data it is.
      Parameters:
      val - The value to be wrapped in a byReference.
      signature - The signature (using Objective-C type encodings) of the value.
      Returns:
      A pointer to the reference that can be passed in a C function.
      See Also:

    • getAsReferenceWrapper

      public static com.sun.jna.ptr.ByReference getAsReferenceWrapper(Object val, String signature)
      Wraps the given value in the appropriate ByReference subclass according to the provided signature. This is a useful method in cases where you need to pass a parameter to a C-function by reference, but you don't necessarily know what type of data it is.
      Parameters:
      val - The value to be wrapped in a byReference.
      signature - The signature (using Objective-C type encodings) of the value.
      Returns:
      The ByReference object that contains the pointer that can be passed to a c function.
      See Also:

    • createProxy

      public static long createProxy(Recipient client)
      Registers a Java object with the Objective-C runtime so that it can begin to receive messages from it. This will create an Objective-C proxy that passes messages to the Recipient object. This step is automatically handled by the NSObject class inside its init() method.
      Parameters:
      client - a Recipient object.
      Returns:
      a long.

    • getJavaPeer

      public static Recipient getJavaPeer(long nsObject)
      Returns the Java peer recipient for a native Objective-C object if it exists. This will return null if nsObject is not an WLProxy object that has been previously registered with a Recipient.
      Parameters:
      nsObject - a long.
      Returns:
      a Recipient object.