MSFMassifApi

Objective-C


@interface MSFMassifApi : NSObject {
  void *swigCPtr;
  BOOL swigCMemOwn;
}

Swift

class MSFMassifApi : NSObject

The facade API, as an app sees it (experimental, #146). No SDK type may appear in a signature (#159), so the C ABI can carry the whole class: anything naming one belongs in MassifInterop, and scripts/check-facade-abi.sh fails the build otherwise.

  • Builds an object from a JSON spec and registers it under a kind and id. An existing id with an identical spec returns its handle; a different spec fails. Keys the factory does not take are applied as properties, unknown ones dropped with a warning.

    Declaration

    Objective-C

    + (int)create:(NSString *)kind
     objectId:(NSString *)objectId
         json:(NSString *)json;

    Swift

    class func create(_ kind: String!, objectId: String!, json: String!) -> Int32

    Parameters

    kind

    The object kind: “source”, “style” or “layer”.
    objectId

    The caller’s name for the object.
    json

    The spec.

    Return Value

    The handle. @throws NSException If the spec does not parse, names no known type, or the id is taken by a different spec.

  • Subscribes to an event on an object.

    Declaration

    Objective-C

    + (int)on:(int)handle
         event:(NSString *)event
      listener:(MSFEventListener *)listener
      delivery:(int)delivery
      coalesce:(BOOL)coalesce
    projection:(NSString *)projection
       consume:(BOOL)consume
    throttleMs:(int)throttleMs;

    Swift

    class func on(_ handle: Int32, event: String!, listener: MSFEventListener!, delivery: Int32, coalesce: Bool, projection: String!, consume: Bool, throttleMs: Int32) -> Int32

    Parameters

    handle

    The target, from create or MassifInterop.adopt.
    event

    The event name, e.g. “map.clicked”.
    listener

    Called when it fires.
    delivery

    0 origin, 1 UI, 2 background.
    coalesce

    Whether a queued event is replaced rather than joined by the next one.
    projection

    The well-known name position reads default to during the handler, e.g. “EPSG:4326”. Empty leaves the map’s own projection; a payload read later must name it per read (see getPos).
    consume

    Whether the listener’s return value can claim the event, stopping later handlers and marking the gesture handled. Requires delivery 0: the SDK asks synchronously.
    throttleMs

    Drops events within this many milliseconds of the last one delivered to this handler; 0 is off. Refused on a consuming subscription.

    Return Value

    The subscription, or 0 when the handle is stale, the projection is unknown, a consuming subscription asked for another thread, or a consuming one asked to be throttled.

  • Subscribes to an event on an object.

    Declaration

    Objective-C

    + (int)on:(int)handle
         event:(NSString *)event
      listener:(MSFEventListener *)listener
      delivery:(int)delivery
      coalesce:(BOOL)coalesce
    projection:(NSString *)projection
       consume:(BOOL)consume;

    Swift

    class func on(_ handle: Int32, event: String!, listener: MSFEventListener!, delivery: Int32, coalesce: Bool, projection: String!, consume: Bool) -> Int32

    Parameters

    handle

    The target, from create or MassifInterop.adopt.
    event

    The event name, e.g. “map.clicked”.
    listener

    Called when it fires.
    delivery

    0 origin, 1 UI, 2 background.
    coalesce

    Whether a queued event is replaced rather than joined by the next one.
    projection

    The well-known name position reads default to during the handler, e.g. “EPSG:4326”. Empty leaves the map’s own projection; a payload read later must name it per read (see getPos).
    consume

    Whether the listener’s return value can claim the event, stopping later handlers and marking the gesture handled. Requires delivery 0: the SDK asks synchronously.

    Return Value

    The subscription, or 0 when the handle is stale, the projection is unknown, a consuming subscription asked for another thread, or a consuming one asked to be throttled.

  • Subscribes to an event on an object.

    Declaration

    Objective-C

    + (int)on:(int)handle
         event:(NSString *)event
      listener:(MSFEventListener *)listener
      delivery:(int)delivery
      coalesce:(BOOL)coalesce
    projection:(NSString *)projection;

    Swift

    class func on(_ handle: Int32, event: String!, listener: MSFEventListener!, delivery: Int32, coalesce: Bool, projection: String!) -> Int32

    Parameters

    handle

    The target, from create or MassifInterop.adopt.
    event

    The event name, e.g. “map.clicked”.
    listener

    Called when it fires.
    delivery

    0 origin, 1 UI, 2 background.
    coalesce

    Whether a queued event is replaced rather than joined by the next one.
    projection

    The well-known name position reads default to during the handler, e.g. “EPSG:4326”. Empty leaves the map’s own projection; a payload read later must name it per read (see getPos).

    Return Value

    The subscription, or 0 when the handle is stale, the projection is unknown, a consuming subscription asked for another thread, or a consuming one asked to be throttled.

  • Subscribes to an event on an object.

    Declaration

    Objective-C

    + (int)on:(int)handle
       event:(NSString *)event
    listener:(MSFEventListener *)listener
    delivery:(int)delivery
    coalesce:(BOOL)coalesce;

    Swift

    class func on(_ handle: Int32, event: String!, listener: MSFEventListener!, delivery: Int32, coalesce: Bool) -> Int32

    Parameters

    handle

    The target, from create or MassifInterop.adopt.
    event

    The event name, e.g. “map.clicked”.
    listener

    Called when it fires.
    delivery

    0 origin, 1 UI, 2 background.
    coalesce

    Whether a queued event is replaced rather than joined by the next one.

    Return Value

    The subscription, or 0 when the handle is stale, the projection is unknown, a consuming subscription asked for another thread, or a consuming one asked to be throttled.

  • Registers how to reach the app’s UI thread. post() is called on the producing thread and must get onto the UI thread and call drain; without a dispatcher, UI subscriptions run inline on the producing thread.

    Declaration

    Objective-C

    + (void)setUiDispatcher:(MSFUiDispatcher *)dispatcher;

    Swift

    class func setUiDispatcher(_ dispatcher: MSFUiDispatcher!)

    Parameters

    dispatcher

    The dispatcher, or null to go back to inline delivery.

  • Runs the handlers waiting for this thread. Called by whatever the dispatcher posted.

    Declaration

    Objective-C

    + (int)drain;

    Swift

    class func drain() -> Int32

    Return Value

    How many were delivered.

  • Installs the click bridge of a layer given by handle, so its clicks become facade events on that handle: a vector tile layer’s (feature.clicked), a vector layer’s elements and a celestial layer’s objects. The listener already there is chained. No object API is needed: the layer is reached by its handle.

    Declaration

    Objective-C

    + (BOOL)attachVectorTileEvents:(int)handle;

    Swift

    class func attachVectorTileEvents(_ handle: Int32) -> Bool

    Return Value

    False if the handle is not a layer of the matching kind.

  • Declaration

    Objective-C

    + (BOOL)attachVectorElementEvents:(int)handle;

    Swift

    class func attachVectorElementEvents(_ handle: Int32) -> Bool

  • Declaration

    Objective-C

    + (BOOL)attachCelestialEvents:(int)handle;

    Swift

    class func attachCelestialEvents(_ handle: Int32) -> Bool

  • Installs the load bridge of a tile layer given by handle: tiles.loaded fires on it when the visible tiles have arrived, tiles.preloaded for the ring around them.

    Declaration

    Objective-C

    + (BOOL)attachTileLoadEvents:(int)handle;

    Swift

    class func attachTileLoadEvents(_ handle: Int32) -> Bool

    Return Value

    False if the handle is not a tile layer.

  • Installs the frame bridge of a renderer given by handle (the mapRenderer of a map view): frame.before and frame.after fire on it from the GL thread, around every drawn frame.

    Declaration

    Objective-C

    + (BOOL)attachFrameEvents:(int)handle;

    Swift

    class func attachFrameEvents(_ handle: Int32) -> Bool

    Return Value

    False if the handle is not a renderer.

  • Removes one subscription.

    Declaration

    Objective-C

    + (BOOL)off:(int)subscription;

    Swift

    class func off(_ subscription: Int32) -> Bool

  • Removes every handler of one event on one object.

    Declaration

    Objective-C

    + (int)offEvent:(int)handle event:(NSString *)event;

    Swift

    class func offEvent(_ handle: Int32, event: String!) -> Int32

  • Removes every handler on one object.

    Declaration

    Objective-C

    + (int)offAll:(int)handle;

    Swift

    class func offAll(_ handle: Int32) -> Int32

  • Drops an id and the context’s reference to the object behind it.

    Declaration

    Objective-C

    + (BOOL)unregisterObject:(NSString *)kind objectId:(NSString *)objectId;

    Swift

    class func unregisterObject(_ kind: String!, objectId: String!) -> Bool

    Return Value

    True when the id existed.

  • Returns the handle registered under a kind and id, or 0.

    Declaration

    Objective-C

    + (int)findObject:(NSString *)kind objectId:(NSString *)objectId;

    Swift

    class func findObject(_ kind: String!, objectId: String!) -> Int32

  • Whether a handle still resolves. A binding needs this to tell “destroyed” from “never existed” without a property read that might legitimately fail for another reason.

    Declaration

    Objective-C

    + (BOOL)isValid:(int)handle;

    Swift

    class func isValid(_ handle: Int32) -> Bool

  • Writes a property. The path may walk object properties (“fogOptions.rangeStart”) and end in a bag key (“params.water_color”); a bag also takes every key at once as a JSON object.

    Declaration

    Objective-C

    + (int)setFloat:(int)handle path:(NSString *)path value:(double)value;

    Swift

    class func setFloat(_ handle: Int32, path: String!, value: Double) -> Int32

    Return Value

    0 on success, see the Result enum otherwise.

  • Declaration

    Objective-C

    + (int)setInt:(int)handle path:(NSString *)path value:(long long)value;

    Swift

    class func setInt(_ handle: Int32, path: String!, value: Int64) -> Int32

  • Declaration

    Objective-C

    + (int)setBool:(int)handle path:(NSString *)path value:(BOOL)value;

    Swift

    class func setBool(_ handle: Int32, path: String!, value: Bool) -> Int32

  • Declaration

    Objective-C

    + (int)setString:(int)handle path:(NSString *)path value:(NSString *)value;

    Swift

    class func setString(_ handle: Int32, path: String!, value: String!) -> Int32

  • Writes several properties from one JSON object of path to value, in one crossing. Every key is attempted and the first failure is returned.

    Declaration

    Objective-C

    + (int)setAll:(int)handle
          json:(NSString *)json
    projection:(NSString *)projection;

    Swift

    class func setAll(_ handle: Int32, json: String!, projection: String!) -> Int32

    Return Value

    0 when every key applied, see the Result enum otherwise.

  • Writes several properties from one JSON object of path to value, in one crossing. Every key is attempted and the first failure is returned.

    Declaration

    Objective-C

    + (int)setAll:(int)handle json:(NSString *)json;

    Swift

    class func setAll(_ handle: Int32, json: String!) -> Int32

    Return Value

    0 when every key applied, see the Result enum otherwise.

  • Writes a position property in a named projection - the write counterpart of getPos.

    Declaration

    Objective-C

    + (int)setPos:(int)handle
          path:(NSString *)path
          json:(NSString *)json
    projection:(NSString *)projection;

    Swift

    class func setPos(_ handle: Int32, path: String!, json: String!, projection: String!) -> Int32

    Parameters

    json

    The position as [x, y] or [x, y, z], bounds as a pair of them.
    projection

    The well-known name the value is in, e.g. “EPSG:3857”. Empty behaves exactly like setString.

  • Writes a position property in a named projection - the write counterpart of getPos.

    Declaration

    Objective-C

    + (int)setPos:(int)handle path:(NSString *)path json:(NSString *)json;

    Swift

    class func setPos(_ handle: Int32, path: String!, json: String!) -> Int32

    Parameters

    json

    The position as [x, y] or [x, y, z], bounds as a pair of them.

  • Points an object property at another registered object - a layer’s data source, a decoder’s style. Pass 0 to clear it. A value of the wrong class is an error, not a crash.

    Declaration

    Objective-C

    + (int)setObject:(int)handle path:(NSString *)path value:(int)value;

    Swift

    class func setObject(_ handle: Int32, path: String!, value: Int32) -> Int32

  • The object an object property points at, as a handle the caller owns - how a child is shared. Pass it to destroy when done: it is a reference, so the object is untouched.

    Declaration

    Objective-C

    + (int)getObject:(int)handle path:(NSString *)path;

    Swift

    class func getObject(_ handle: Int32, path: String!) -> Int32

    Return Value

    0 when the path does not resolve, is not an object property, or is null.

  • Reads a property. Returns the fallback when the path does not resolve, so a caller that does not care about the reason does not have to check twice.

    Declaration

    Objective-C

    + (double)getFloat:(int)handle
              path:(NSString *)path
      defaultValue:(double)defaultValue;

    Swift

    class func getFloat(_ handle: Int32, path: String!, defaultValue: Double) -> Double

  • Declaration

    Objective-C

    + (long long)getInt:(int)handle
               path:(NSString *)path
       defaultValue:(long long)defaultValue;

    Swift

    class func getInt(_ handle: Int32, path: String!, defaultValue: Int64) -> Int64

  • Declaration

    Objective-C

    + (BOOL)getBool:(int)handle
            path:(NSString *)path
    defaultValue:(BOOL)defaultValue;

    Swift

    class func getBool(_ handle: Int32, path: String!, defaultValue: Bool) -> Bool

  • Declaration

    Objective-C

    + (NSString *)getString:(int)handle
                   path:(NSString *)path
           defaultValue:(NSString *)defaultValue;

    Swift

    class func getString(_ handle: Int32, path: String!, defaultValue: String!) -> String!

  • Reads a position property as JSON, in the projection asked for: [x, y] or [x, y, z], bounds as a pair of them.

    Declaration

    Objective-C

    + (NSString *)getPos:(int)handle
                path:(NSString *)path
          projection:(NSString *)projection;

    Swift

    class func getPos(_ handle: Int32, path: String!, projection: String!) -> String!

    Parameters

    projection

    The well-known name, e.g. “EPSG:3857”. Empty means the running event handler’s projection, else WGS84 degrees (#159); setString takes positions the same way, so a read/write round trip is safe.

    Return Value

    The JSON, or an empty string when the path does not resolve.

  • Reads a position property as JSON, in the projection asked for: [x, y] or [x, y, z], bounds as a pair of them.

    Declaration

    Objective-C

    + (NSString *)getPos:(int)handle path:(NSString *)path;

    Swift

    class func getPos(_ handle: Int32, path: String!) -> String!

    Return Value

    The JSON, or an empty string when the path does not resolve.

  • Runs a method on an object. The result is always a handle the caller owns - pass it to destroy. An object result is that object; anything else is a JSON document, read with an empty path.

    Declaration

    Objective-C

    + (int)call:(int)handle method:(NSString *)method argsJson:(NSString *)argsJson;

    Swift

    class func call(_ handle: Int32, method: String!, argsJson: String!) -> Int32

    Parameters

    method

    The method name, e.g. “loadTile”.
    argsJson

    The arguments as a JSON array, e.g. “[[8467,5852,14]]”. Empty for none.

    Return Value

    The result handle. @throws NSException If the handle is stale, the method is unknown, the arguments do not fit it, or the method failed.

  • Runs a method on an object. The result is always a handle the caller owns - pass it to destroy. An object result is that object; anything else is a JSON document, read with an empty path.

    Declaration

    Objective-C

    + (int)call:(int)handle method:(NSString *)method;

    Swift

    class func call(_ handle: Int32, method: String!) -> Int32

    Parameters

    method

    The method name, e.g. “loadTile”.

    Return Value

    The result handle. @throws NSException If the handle is stale, the method is unknown, the arguments do not fit it, or the method failed.

  • The same, on a worker thread, with the result delivered as event on the object (subscribe first). The payload is the result - an object handle or a JSON document, 0 on failure - and is freed once the handlers have run.

    Declaration

    Objective-C

    + (int)callAsync:(int)handle
          method:(NSString *)method
        argsJson:(NSString *)argsJson
           event:(NSString *)event;

    Swift

    class func callAsync(_ handle: Int32, method: String!, argsJson: String!, event: String!) -> Int32

    Return Value

    The call’s id, for cancelCall. @throws NSException If the handle is stale, the method is unknown, or the argument JSON does not parse. A failure while running is a payload of 0.

  • Cancels a queued or running async call: it will not start and no event fires, but a call already running is not aborted.

    Declaration

    Objective-C

    + (BOOL)cancelCall:(int)call;

    Swift

    class func cancelCall(_ call: Int32) -> Bool

    Return Value

    True when the call was queued or running, false when it had already finished.

  • Cancels every queued or running call on an object.

    Declaration

    Objective-C

    + (int)cancelCalls:(int)handle;

    Swift

    class func cancelCalls(_ handle: Int32) -> Int32

    Return Value

    How many were cancelled.

  • Reads a bulk numeric result as a flat array: double[] in Java, NSData over the raw doubles in Objective-C.

    Declaration

    Objective-C

    + (NSData *)getDoubles:(int)handle;

    Swift

    class func getDoubles(_ handle: Int32) -> Data!

    Return Value

    The values, or empty when the handle is not a numeric result.

  • Reads a binary property as raw bytes - byte[] in Java, NSData in Objective-C - not as the SDK’s BinaryData, so this class names no SDK type (#159).

    Declaration

    Objective-C

    + (NSData *)getData:(int)handle path:(NSString *)path;

    Swift

    class func getData(_ handle: Int32, path: String!) -> Data!

    Parameters

    path

    The path to the property, e.g. “data” on a tile. Empty when the handle is the blob itself.

    Return Value

    The data, empty when the path does not resolve to one.

  • Registers raw bytes as a data object a spec can name: {"type":"bitmap","data":"<id>"} decodes an image from them, with no file and no text encoding in between. The bytes are copied once. byte[] in Java, NSData in Objective-C.

    Declaration

    Objective-C

    + (int)createData:(NSString *)objectId bytes:(NSData *)bytes;

    Swift

    class func createData(_ objectId: String!, bytes: Data!) -> Int32

    Parameters

    objectId

    The caller’s name for the data. Must be free.

    Return Value

    The handle. @throws NSException When the id is taken or the bytes are empty.

  • Drops a handle’s id, and with it the context’s reference to the object.

    Declaration

    Objective-C

    + (BOOL)destroy:(int)handle;

    Swift

    class func destroy(_ handle: Int32) -> Bool

    Return Value

    True when the handle was live.

  • Undocumented

    Declaration

    Objective-C

    -(void)dealloc;

    Swift

    func dealloc()