MSFMassifApi

Objective-C


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

Swift

class MSFMassifApi : NSObject

The facade API, as an app sees it.

Experimental and incomplete: only the property verbs exist so far, and they address the default context. See https://github.com/massif-maps/MassifMaps/issues/146.

Every call returns a result code rather than throwing, because this is a verification surface rather than the final binding.

NO SDK TYPE APPEARS IN ANY SIGNATURE HERE, and that is the invariant to keep (#159): handles, strings, numbers and the facade’s own EventListener/UiDispatcher, nothing else. It is what lets the C ABI carry the whole class and a hand-written binding do the same. Anything that must name an SDK type belongs in MassifInterop; scripts/check-facade-abi.sh fails the build when one lands here.

  • Builds an object from a JSON spec and registers it under a kind and id.

    Creating an id that already exists with an IDENTICAL spec returns the existing handle, so two maps can share one source without coordinating. A different spec under the same id fails. Keys the factory does not need are applied as properties, and a key the SDK does not know is 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.
    projection

    The well-known name of the projection this handler’s position reads default to, e.g. “EPSG:4326”. Empty leaves them in the map’s own projection. It applies for the duration of the call, so a payload kept and read afterwards has to name the projection per read - see getPos.
    consume

    Whether the listener’s return value can claim the event, stopping it reaching later handlers and telling the SDK the gesture was handled. LAST, and defaulted, so the shape of a subscription that does not claim is unchanged - and so a binding can tell the two apart by arity or by selector name. The SDK asks that question synchronously, so a consuming subscription must be delivery 0.
    throttleMs

    Drops events arriving within this many milliseconds of the last one delivered to this handler; 0 is off. A window rather than a timer, because dropping is the point - a queued handler would read a payload the emit has already freed. Refused on a consuming subscription: a dropped click is one the SDK is still waiting on.

    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.
    projection

    The well-known name of the projection this handler’s position reads default to, e.g. “EPSG:4326”. Empty leaves them in the map’s own projection. It applies for the duration of the call, so a payload kept and read afterwards has to name the projection per read - see getPos.
    consume

    Whether the listener’s return value can claim the event, stopping it reaching later handlers and telling the SDK the gesture was handled. LAST, and defaulted, so the shape of a subscription that does not claim is unchanged - and so a binding can tell the two apart by arity or by selector name. The SDK asks that question synchronously, so a consuming subscription must be delivery 0.

    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.
    projection

    The well-known name of the projection this handler’s position reads default to, e.g. “EPSG:4326”. Empty leaves them in the map’s own projection. It applies for the duration of the call, so a payload kept and read afterwards has to name the projection 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.

    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, for subscriptions that asked for it.

    The dispatcher’s post() is called from whatever thread produced the event, and must get onto the UI thread and call drain. Without one, UI subscriptions run inline on the producing thread and the facade warns once.

    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.

  • 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 it may end in the KEY of a bag: “params.water_color” on a style.

    A bag also takes every key at once, as a JSON object - one crossing rather than one per parameter: setString(style, “params”, “{\"water_color”:“#0af”}“).

    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.

    {"fogOptions.rangeStart": 2, "visible": false} is one crossing rather than one per key, which is what a binding’s apply({...}) used to cost. Every key is attempted and the first failure is returned, so one bad name does not hide the other writes.

    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.

    {"fogOptions.rangeStart": 2, "visible": false} is one crossing rather than one per key, which is what a binding’s apply({...}) used to cost. Every key is attempted and the first failure is returned, so one bad name does not hide the other writes.

    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.

    setString takes a position in the projection the running handler asked for, and in WGS84 outside one, which is right until an app holds coordinates in another system: those had to be converted by hand, and a mistake showed up as a plausible position somewhere else.

    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.

    setString takes a position in the projection the running handler asked for, and in WGS84 outside one, which is right until an app holds coordinates in another system: those had to be converted by hand, and a mistake showed up as a plausible position somewhere else.

    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.

    The value’s class is checked against the property’s before anything is cast, so pointing a style property at a source is an error rather than 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.

    The counterpart of setObject, and the only way to SHARE a child: an overlay drawing the base map’s tiles with a different style needs that source, and without this it had to be built a second time. Pass it to destroy when done - it is a reference, not a copy, so destroying it does not touch the object itself.

    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.

    A position is [x, y] or [x, y, z] and bounds are a pair of them, so one call covers clickPos, featurePos and dataExtent alike.

    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 projection the running event handler asked for, and WGS84 when there is none - a facade position is DEGREES unless the caller says otherwise (#159). A position written back with setString is taken in the same projection, 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.

    A position is [x, y] or [x, y, z] and bounds are a pair of them, so one call covers clickPos, featurePos and dataExtent alike.

    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, or it stays registered. An object result is that object; anything else is a JSON document, read with an empty path:

    int tile = MassifApi.call(source, “loadTile”, “[[8467,5852,14]]”); byte[] bytes = MassifApi.getData(tile, “data”); MassifApi.destroy(tile);

    int result = MassifApi.call(layer, “getElevations”, “[[[5.76,45.24],[5.77,45.25]]]”); double first = MassifApi.getFloat(result, “0”, 0);

    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, or it stays registered. An object result is that object; anything else is a JSON document, read with an empty path:

    int tile = MassifApi.call(source, “loadTile”, “[[8467,5852,14]]”); byte[] bytes = MassifApi.getData(tile, “data”); MassifApi.destroy(tile);

    int result = MassifApi.call(layer, “getElevations”, “[[[5.76,45.24],[5.77,45.25]]]”); double first = MassifApi.getFloat(result, “0”, 0);

    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 an event on the object.

    Subscribe to event with on first; the payload is the result - an object handle directly, or a JSON document a path reads out of (“” for the whole thing). A payload of 0 means the call failed. The payload is freed once the handlers have run, exactly like a map event’s, so nothing has to be destroyed by hand.

    MassifApi.on(source, “loadTile.done”, listener, 1, false); int call = MassifApi.callAsync(source, “loadTile”, “[[8467,5852,14]]”, “loadTile.done”);

    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 reported as a payload of 0, since the call has returned by then.

  • Cancels a queued or running async call.

    Cancelling stops the call being STARTED and stops its result being DELIVERED, but cannot abort one already running - loadTile has no cancellation token to pass on. Either way no event fires.

    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.

    A profile over a track is thousands of numbers, so they arrive as one array rather than as JSON or as a proxy read an element at a time - double[] in Java, NSData over the raw doubles in Objective-C:

    int result = MassifApi.call(layer, “getElevations”, “[[[5.76,45.24],[5.77,45.25]]]”); double[] metres = MassifApi.getDoubles(result); MassifApi.destroy(result);

    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 without turning it into a string.

    The blob crosses as RAW BYTES - byte[] in Java, NSData in Objective-C - not as the SDK’s BinaryData. That is the point: this class names no SDK type, so a hand-written JNI, , N-API or dart:ffi layer could carry the whole of it (#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.

  • Drops a handle’s id, and with it the context’s reference to the object. Addressed by handle rather than by kind and id, which is what a caller holding a result has.

    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()