Module javaobjectivecbridge
Package ca.weblite.objc

Class Client

java.lang.Object
ca.weblite.objc.Client
public class Client extends Object

An object-oriented wrapper around the RuntimeUtils static methods for interacting with the Objective-C runtime.

A client object stores settings about whether to coerce inputs and/or outputs from messages. There are two global instances of this class that are used most often:

  1. getInstance(): The default client with settings to coerce both inputs and outputs. If you need to make a direct call to the Objective-C runtime, this is usually the client that you would use.
  2. getRawClient(): Reference to a simple client that is set to not coerce input and output. This is handy if you want to pass in the raw Pointers as parameters, and receive raw pointers as output.

  • Method Details

    • getInstance

      public static Client getInstance()
      Retrieves the global reference to a client that has both input coercion and output coercion enabled.
      Returns:
      Singleton instance.

    • getRawClient

      public static Client getRawClient()
      Retrieves singleton instance to a simple client that has type coercion disabled for both inputs and outputs.
      Returns:
      a Client object.

    • setCoerceInputs

      @Deprecated public Client setCoerceInputs(boolean coerceInputs)
      Deprecated.
      Use getRawClient() to get a client with coercion off. Use getInstance() to get a client with coercion on.
      Set the coerceInputs flag. Setting this to true will cause all subsequent requests to coerce the input (i.e. convert Java parameters to corresponding C-types).
      Parameters:
      coerceInputs - Whether to coerce inputs to messages.
      Returns:
      Self for chaining.
      See Also:

    • setCoerceOutputs

      @Deprecated public Client setCoerceOutputs(boolean coerceOutputs)
      Deprecated.
      Use getRawClient() to get a client with coercion off. Use getInstance() to get a client with coercion on.
      Sets the coerceOutputs flag. Setting this to true will cause all subsequent requests to coerce the output (i.e.convert C return values to corresponding Java types.
      Parameters:
      coerceOutputs - Whether to coerce the outputs of messages.
      Returns:
      Self for chaining.
      See Also:

    • getCoerceInputs

      public boolean getCoerceInputs()
      Returns the coerceInputs flag. If this returns true, then it means that the client is currently set to coerce all inputs to messages.
      Returns:
      True if input coercion is enabled.
      See Also:

    • getCoerceOutputs

      public boolean getCoerceOutputs()
      Returns the coerceOutputs flag. If this returns true, then it means that the client is currently set to coerce all outputs of messages.
      Returns:
      True if output coercion is enabled.
      See Also:

    • send

      public Object send(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      Sends a message to an Objective-C object. 
       
 String hello = (String)Client.getInstance()
      .send(cls("NSString"), sel("stringWithUTF8String:"), "Hello");
      Parameters:
      receiver - A pointer to the object to which the message is being sent.
      selector - A pointer to the selector to call on the target.
      args - Variable arguments of the message.
      Returns:
      The return value of the message call.

    • send

      public Object send(com.sun.jna.Pointer receiver, String selector, Object... args)
      Sends a message to an Objective-C object. String selector version. 
       
 String hello = (String)Client.getInstance()
      .send(cls("NSString"), "stringWithUTF8String:", "Hello");
      Parameters:
      receiver - A pointer to the object to which the message is being sent.
      selector - The string selector. (E.g. "addObject:atIndex:")
      args - Variable arguments of the message.
      Returns:
      The return value of the message call.

    • send

      public Object send(String receiver, com.sun.jna.Pointer selector, Object... args)
      Sends a message to an Objective-C object. String target and Pointer selector version. Typically this variant is used when you need to call a class method (e.g. to instantiate a new object). In this case the receiver is interpreted as a class name. 
       
 String hello = (String)Client.getInstance()
      .send("NSString", sel("stringWithUTF8String:"), "Hello");
      Parameters:
      receiver - The name of a class to send the message to.
      selector - Pointer to the selector.
      args - Variable arguments of the message.
      Returns:
      The return value of the message call.

    • send

      public Object send(String receiver, String selector, Object... args)
      Sends a message to an Objective-C object. String target and String selector version. Typically this variant is used when you need to call a class method (e.g. to instantiate a new object). In this case the receiver is interpreted as a class name. 
       
 String hello = (String)Client.getInstance()
      .send("NSString", "stringWithUTF8String:", "Hello");
      Parameters:
      receiver - The name of a class to send the message to.
      selector - Pointer to the selector.
      args - Variable arguments of the message.
      Returns:
      The return value of the message call.

    • send

      public Object send(Peerable proxy, com.sun.jna.Pointer selector, Object... args)
      Sends a message to an Objective-C object. Peerable target/Pointer selector variant. This variant is used if you have a Peerable object that is wrapping the Object pointer. E.g. Both the Proxy class and NSObject class implement this interface. 
       
 Proxy array = Client.getInstance().sendProxy("NSMutableArray", sel("array"));
 String hello = (String)Client
      .getInstance().send(array, sel("addObject:atIndex"), "Hello", 2);
      Parameters:
      selector - Pointer to the selector.
      args - Variable arguments of the message.
      proxy - a Peerable object.
      Returns:
      The return value of the message call.

    • send

      public Object send(Peerable proxy, String selector, Object... args)
      Sends a message to an Objective-C object. Peerable target/String selector variant. This variant is used if you have a Peerable object that is wrapping the Object pointer. E.g. Both the Proxy class and NSObject class implement this interface. 
       
 Proxy array = Client.getInstance().sendProxy("NSMutableArray", "array");
 String hello = (String)Client
      .getInstance().send(array, "addObject:atIndex", "Hello", 2);
      Parameters:
      selector - Pointer to the selector.
      args - Variable arguments of the message.
      proxy - a Peerable object.
      Returns:
      The return value of the message call.

    • sendPointer

      public com.sun.jna.Pointer sendPointer(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      A wrapper around send() to ensure that a pointer is returned from the message.
      Parameters:
      receiver - The object to which the message is being sent.
      selector - The selector to call on the receiver.
      args - Variable arguments to the message.
      Returns:
      A pointer result from the message invocation.

    • sendPointer

      public com.sun.jna.Pointer sendPointer(com.sun.jna.Pointer receiver, String selector, Object... args)
      A wrapper around send() to ensure that a pointer is returned from the message.
      Parameters:
      receiver - The object to which the message is being sent.
      selector - The selector to call on the receiver.
      args - Variable arguments to the message.
      Returns:
      A pointer result from the message invocation.

    • sendPointer

      public com.sun.jna.Pointer sendPointer(String receiver, com.sun.jna.Pointer selector, Object... args)
      A wrapper around send() to ensure that a pointer is returned from the message.
      Parameters:
      receiver - The object to which the message is being sent.
      selector - The selector to call on the receiver.
      args - Variable arguments to the message.
      Returns:
      A pointer result from the message invocation.

    • sendPointer

      public com.sun.jna.Pointer sendPointer(String receiver, String selector, Object... args)
      A wrapper around send() to ensure that a pointer is returned from the message.
      Parameters:
      receiver - The object to which the message is being sent.
      selector - The selector to call on the receiver.
      args - Variable arguments to the message.
      Returns:
      A pointer result from the message invocation.

    • sendProxy

      public Proxy sendProxy(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args)
      A wrapper around send() to ensure that a Proxy object is returned from the message.
      Parameters:
      receiver - The object to which the message is being sent.
      selector - The selector to call on the receiver.
      args - Variable arguments to the message.
      Returns:
      A Proxy object wrapper of the result from the message invocation.

    • sendProxy

      public Proxy sendProxy(String receiver, com.sun.jna.Pointer selector, Object... args)
      A wrapper around send() to ensure that a Proxy object is returned from the message.
      Parameters:
      receiver - The object to which the message is being sent.
      selector - The selector to call on the receiver.
      args - Variable arguments to the message.
      Returns:
      A Proxy object wrapper of the result from the message invocation.

    • sendProxy

      public Proxy sendProxy(String receiver, String selector, Object... args)
      A wrapper around send() to ensure that a Proxy object is returned from the message.
      Parameters:
      receiver - The object to which the message is being sent.
      selector - The selector to call on the receiver.
      args - Variable arguments to the message.
      Returns:
      A Proxy object wrapper of the result from the message invocation.

    • sendProxy

      public Proxy sendProxy(com.sun.jna.Pointer receiver, String selector, Object... args)
      A wrapper around send() to ensure that a Proxy object is returned from the message.
      Parameters:
      receiver - The object to which the message is being sent.
      selector - The selector to call on the receiver.
      args - Variable arguments to the message.
      Returns:
      A Proxy object wrapper of the result from the message invocation.

    • chain

      public Proxy chain(String cls, com.sun.jna.Pointer selector, Object... args)

      chain.

      Parameters:
      cls - a String object.
      selector - a Pointer object.
      args - a Object object.
      Returns:
      a Proxy object.

    • chain

      public Proxy chain(String cls, String selector, Object... args)

      chain.

      Parameters:
      cls - a String object.
      selector - a String object.
      args - a Object object.
      Returns:
      a Proxy object.

    • newObject

      public PeerableRecipient newObject(Class<? extends PeerableRecipient> cls)
      Creates a new peerable and receivable object of the specified class. This will create the Objective-C peer and link it to this new class.
      Parameters:
      cls - The class of the instance that should be created.
      Returns:
      A PeerableRecipient object that is connected to an objective-c peer object.

    • send

      public Object send(Message... messages)
      Sends an array of messages in a chain.
      Parameters:
      messages - a Message object.
      Returns:
      a Object object.

    • buildMessageChain

      public Message[] buildMessageChain(Object... parameters)
      Builds a chain of messages that can be executed together at a later time.
      Parameters:
      parameters - a Object object.
      Returns:
      an array of Message objects.