RVP_Cocoa_SDK

public class RVP_Cocoa_SDK : NSObject
extension RVP_Cocoa_SDK: URLSessionDelegate
extension RVP_Cocoa_SDK: Sequence

This class represents the public interface to the White Dragon Great Rift Valley Platform BAOBAB Server iOS SDK framework.

The SDK is a Swift-only shared framework for use by Swift applications, targeting iOS 11 or above.

This system works by caching retrieved objects in the main SDK instance, and referencing them. This is different from the PHP SDK, where each object is an independent instance and state. Swift likes objects to be referenced, as opposed to copied, so we honor that. Since the SDK is really an ORM, this makes sense.

This class follows the Sequence protocol, so its cached instances can be iterated and subscripted. These instances are kept sorted by ID and database.

The SDK opens a session to the server upon instantiation, and maintains that throughout its lifecycle. This happens whether or not a login is done.

It can also have an open session passed in at instantiation, and it will use that session.

Public Stored Properties

  • This is a special “settable” property with the center of a radius search. If the object already has a “distance” property returned from the server, this is ignored. Otherwise, if it is provided, and the object has a long/lat, the “distance” read-only property will return a Vincenty’s Formulae distance in Kilometers from this center.

    Declaration

    Swift

    public var searchLocation: CLLocationCoordinate2D?

Public Instance Methods

  • This is the required default initializer.

    Declaration

    Swift

    public init(serverURI inServerURI: String, serverSecret inServerSecret: String, delegate inDelegate: RVP_Cocoa_SDK_Delegate, loginID inLoginID: String! = nil, password inPassword: String! = nil, timeout inLoginTimeout: Int! = nil, session inURLSession: URLSession? = nil, refCon inRefCon: Any?)

    Parameters

    serverURI

    (REQUIRED) A String, with the URI to a valid BAOBAB Server

    serverSecret

    (REQUIRED) A String, with the Server secret for the target server.

    delegate

    (REQUIRED) A RVP_IOS_SDK_Delegate that will receive updates from the SDK instance.

    loginID

    (OPTIONAL/REQUIRED) A String, with a login ID. If provided, then you must also provide inPassword and inLoginTimeout.

    password

    (OPTIONAL/REQUIRED) A String, with a login password. If provided, then you must also provide inLoginId and inLoginTimeout.

    timeout

    (OPTIONAL/REQUIRED) An Integer value, with the number of seconds the login has to be active. If provided, then you must also provide inLoginId and inPassword.

    session

    (OPTIONAL) This allows the caller to have their own URLSession established (often, there is only one per app), so we can hitch a ride with that session. Otherwise, we create our own. The session must be ephemeral.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

Internal URLSessionDelegate Protocol Methods

  • This is called when the the session becomes invalid for any reason.

    Declaration

    Swift

    public func urlSession(_ session: URLSession, didBecomeInvalidWithError error: Error?)

    Parameters

    session

    The session calling this.

    didBecomeInvalidWithError

    The error (if any) that caused the invalidation.

  • Declaration

    Swift

    public func urlSession(_: URLSession, task inTask: URLSessionTask, didReceive inChallenge: URLAuthenticationChallenge, completionHandler inCompletionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void)

    Parameters

    task

    The session task under way

    didReceive

    The challenge object

    completionHandler

    A function passed in, for dealing with the auth challenge.

Public Types and Structs

  • This is the element type for the Sequence protocol.

    Declaration

    Swift

    public typealias Element = A_RVP_Cocoa_SDK_Object
  • This is how we specify the location for searches.

    • coords: A lat/long coordinate (in degrees) of the location
    • radiusInKm: A distance within which the search will be performed.
    • autoRadiusThreshold: An optional field with a minimum number of results.
    See more

    Declaration

    Swift

    public struct LocationSpecification
  • This is a quick resolver for the basic HTTP status.

    See more

    Declaration

    Swift

    public struct HTTPError : Error

Public Enums

  • This enum lists the various reasons that the server connection may be disconnected.

    These are supplied in the delegate method.

    See more

    Declaration

    Swift

    public enum DisconnectionReason : Int
  • These are the errors that may occur when we are trying to connect to the server.

    See more

    Declaration

    Swift

    public enum SDK_Connection_Errors : Error
  • These are the errors that may occur while we are trying to parse the data returned from the server.

    See more

    Declaration

    Swift

    public enum SDK_Data_Errors : Error
  • These are errors in the SDK operation.

    See more

    Declaration

    Swift

    public enum SDK_Operation_Errors : Error
  • These are supplied in the delegate method.

    See more

    Declaration

    Swift

    public enum SDK_Error
  • These are used to define the types of tokens.

    See more

    Declaration

    Swift

    public enum TokenType : Comparable

Public Computed Properties

  • This is a computed property that will return true if the login is valid.

    Logins only last so long, at which time a new API key should be fetched.

    Returns true, if we are logged in, and the time interval has not passed.

    Declaration

    Swift

    public var isLoggedIn: Bool { get }
  • This is a test to see if the currently logged-in user is a manager.

    Returns true, if we are logged in as at least a manager user.

    Declaration

    Swift

    public var isManager: Bool { get }
  • This is a test to see if the currently logged-in user is a manager.

    Returns true, if we are logged in as the main (“God”) user.

    Declaration

    Swift

    public var isMainAdmin: Bool { get }
  • This is a computed property that will return true if the server connection is valid (regardless of login status).

    NOTE: This will not be valid until after the preliminary communications have completed (the delegate has been called with sdkInstance(_:,loginValid:)).

    Returns true, if we have a list of plugins, which means that we were able to communicate with the server.

    Declaration

    Swift

    public var isValid: Bool { get }
  • Returns an Array of Int, with the current tokens. If logged in, then this will be at least 1, and the current ID of the login. If not logged in, this will return an empty Array.

    Declaration

    Swift

    public var securityTokens: [Int] { get }
  • Returns an Array of Int, with the current tokens. If logged in, then this will be at least 1, and the current ID of the login. If not logged in, this will return an empty Array.

    Declaration

    Swift

    public var personalTokens: [Int] { get }
  • Returns the number of data items in our cache.

    Declaration

    Swift

    public var count: Int { get }
  • Returns true, if we have no items in our cache.

    Declaration

    Swift

    public var isEmpty: Bool { get }
  • Returns the Array of plugins (if the SDK is connected to a valid server).

    Declaration

    Swift

    public var plugins: [String] { get }
  • Accessor for the private API Key storage.

    Declaration

    Swift

    public var apiKey: String { get set }
  • Accessor for the private Server Secret storage.

    Declaration

    Swift

    public var serverSecret: String { get set }
  • Returns the number of personal tokens to be added to new users.

    Declaration

    Swift

    public var number_of_personal_tokens_per_login: Int { get set }
  • Returns the step size, in kilometers, of the auto-radius search.

    Declaration

    Swift

    public var autoRadiusStepSizeInKm: Double { get set }
  • This allows the instance to be treated like a simple Array.

    Declaration

    Swift

    public subscript(inIndex: Int) -> Element? { get }

    Parameters

    _

    The 0-based index we are addressing.

  • This is the Sequence Iterator Struct.

    See more

    Declaration

    Swift

    public struct Iterator : IteratorProtocol
  • This is the login info for our current login. Returns nil, if not logged in.

    Declaration

    Swift

    public var myLoginInfo: RVP_Cocoa_SDK_Login? { get }
  • This is the user info for our current login. Returns nil, if not logged in, or we don’t have any user info associated with the login.

    Declaration

    Swift

    public var myUserInfo: RVP_Cocoa_SDK_User? { get }
  • In some cases, servers may not accept Basic auth headers, so we can force the auth in the query.

    Declaration

    Swift

    public var forceParameterAuth: Bool { get set }

Public Instance Methods

  • This is called with a list of one or more objects to be deleted from the server.

    This will sort through the objects, and will only delete ones we currently have cached. It will figure out whether or not the object is a security object or a data object, and perform the required deletion for each type.

    Declaration

    Swift

    public func deleteObjects(_ inItemArray: [A_RVP_Cocoa_SDK_Object], refCon inRefCon: Any?, uriExtension inURIExtension: String = "")

    Parameters

    inItemArray

    An Array of concrete instances of subclasses of A_RVP_IOS_SDK_Object.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

    uriExtension

    OPTIONAL (empty, if not provided). This is a string that will be attached to the end of the URI. It is completely unvetted and raw.

  • Declaration

    Swift

    public func deleteBy(id inID: Int, andPlugin inPlugin: String, refCon inRefCon: Any?, uriExtension inURIExtension: String = "")

    Parameters

    id

    The ID of the resource to be deleted

    andPlugin

    The plugin to be affected.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

    uriExtension

    OPTIONAL (empty, if not provided). This is a string that will be attached to the end of the URI. It is completely unvetted and raw.

  • This will connect to the server. If login credentials are provided, then it will also log in.

    Declaration

    Swift

    public func connect(loginID inLoginId: String! = nil, password inPassword: String! = nil, timeout inLoginTimeout: Int! = nil, refCon inRefCon: Any?)

    Parameters

    loginId

    (OPTIONAL) A String, with a login ID. If provided, then you must also provide inPassword and inLoginTimeout.

    password

    (OPTIONAL) A String, with a login password. If provided, then you must also provide inLoginId and inLoginTimeout.

    timeout

    (OPTIONAL) A Floating-point value, with the number of seconds the login has to be active. If provided, then you must also provide inLoginId and inPassword.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This is the standard login method.

    When we log in, we go through the process of getting the API key (sending the login info), then getting our login information, our user information (if available), and the baseline plugins.

    After all that, the delegate will be called with the login valid/invalid response.

    Declaration

    Swift

    public func login(loginID inLoginID: String, password inPassword: String, timeout inLoginTimeout: Int, refCon inRefCon: Any?)

    Parameters

    loginID

    (REQUIRED) A String, with a login ID.

    password

    (REQUIRED) A String, with a login password.

    timeout

    (REQUIRED) An Integervalue, with the number of seconds the login has to be active.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This is sends a test to the server, requesting guidance on whether or not to use auth parameters (or the header).

    Declaration

    Swift

    public func sendAuthTypeTest(refCon inRefCon: Any?)

    Parameters

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This is the logout method.

    You must already be logged in for this to do anything. If so, it simply asks the server to log us out.

    Declaration

    Swift

    public func logout(refCon inRefCon: Any?)

    Parameters

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This simply empties our cache, forcing the next load to go out to the server.

    Declaration

    Swift

    public func flushCache()
  • Asks the server to create a user/login pair, with a blank password. This can only be called if you are logged in as a manager.

    Declaration

    Swift

    public func createUserLoginPair(loginString inLoginStringID: String, name inName: String = "", isManager inIsManager: Bool = false, refCon inRefCon: Any?)

    Parameters

    loginString

    The Requested login ID string. It must be unique in the server, and the operation will fail, if it is already taken.

    name

    A requested name for the objects (will be applied to both). It is optional. If not supplied, the Login ID will be used for the name.

    isManager

    If true, then the new instance will be a maneger (default is false, and can be omitted).

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • Asks the server to create a security token (no login). This can only be called if you are logged in as a manager.

    Declaration

    Swift

    public func createSecurityToken(refCon inRefCon: Any?)

    Parameters

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This is a general method for fetching items from the data database, by their numerical IDs.

    Declaration

    Swift

    public func fetchDataItemsByIDs(_ inIntegerIDs: [Int], andPlugin inPlugin: String? = "baseline", withLogins inWithLogins: Bool = false, dontNukeTheLocation inDontNuke: Bool = false, refCon inRefCon: Any?)

    Parameters

    inIntegerIDs

    An Array of Int, with the data database IDs of the data database objects Requested.

    andPlugin

    An optional String, with the required plugin (“people”, “places” or “things”). If nil, then the baseline plugin is invoked, which will fetch any object, regardless of plugin.

    withLogins

    If true (default is false), then this call will ask for the logins associated with users, and only users that have logins. This is ignored, if the user is not a manager.

    dontNukeTheLocation

    Optional. If true, then we keep the search location cached (like in an auto-radius call). Otherwise (default), the search location is reset after this call.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This method fetches every user (with a login) that can be edited by the current manager instance.

    Declaration

    Swift

    public func fetchAllEditableUsersFromServer(refCon inRefCon: Any?)

    Parameters

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This method will initiate a fetch of all types of objects, based upon a list of IDs.

    Declaration

    Swift

    public func fetchBaselineObjectsByID(_ inIDArray: [Int], refCon inRefCon: Any?)

    Parameters

    inIDArray

    An Array of Int, with the data database IDs of the place objects Requested.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This method will initiate a fetch of place objects, based upon a list of IDs.

    Declaration

    Swift

    public func fetchPlaces(_ inPlaceIDArray: [Int], refCon inRefCon: Any?)

    Parameters

    inPlaceIDArray

    An Array of Int, with the data database IDs of the place objects Requested.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This method will initiate a fetch of user objects, based upon a list of IDs.

    Declaration

    Swift

    public func fetchUsers(_ inUserIntegerIDArray: [Int], withLogins inWithLogins: Bool = false, refCon inRefCon: Any?)

    Parameters

    inUserIntegerIDArray

    An Array of Int, with the data database IDs of the user objects Requested.

    withLogins

    If true (default is false), then this call will ask for the logins associated with users, and only users that have logins. This is ignored, if the user is not a manager.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This method will initiate a fetch of user objects, based upon a list of IDs.

    Declaration

    Swift

    public func fetchVisibleUserIDAndNames(refCon inRefCon: Any?)

    Parameters

    inUserIntegerIDArray

    An Array of Int, with the data database IDs of the user objects Requested.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This fetches thing objects from the data database server.

    Declaration

    Swift

    public func fetchThings(_ inThingIntegerIDArray: [Int], refCon inRefCon: Any?)

    Parameters

    inThingIntegerIDArray

    An Array of Int, with the data database IDs of the thing objects Requested.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This fetches thing objects from the data database server.

    Declaration

    Swift

    public func fetchThings(_ inKeys: [String], refCon inRefCon: Any?)

    Parameters

    inKeys

    An Array of String, with the thing keys.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This method will initiate a fetch of login objects, based upon a list of IDs.

    Declaration

    Swift

    public func fetchLogins(_ inLoginIntegerIDArray: [Int], refCon inRefCon: Any?)

    Parameters

    inLoginIntegerIDArray

    An Array of Int, with the security database IDs of the login objects Requested.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This method will initiate a fetch of login objects, based upon a list of IDs.

    Declaration

    Swift

    public func fetchLogins(_ inLoginStringIDArray: [String], refCon inRefCon: Any?)

    Parameters

    inLoginStringIDArray

    An Array of String, with the string login IDs of the login objects Requested.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This method will initiate a fetch of all visible ID objects, listed with types and “owners” (if logged in as “God”).

    Declaration

    Swift

    public func fetchAllTokens(refCon inRefCon: Any?)

    Parameters

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • We ask the server to send us our login object information.

    When we get the information, we parse it, create a new instance of the handler class and cache that instance.

    Declaration

    Swift

    public func fetchMyLoginInfo(refCon inRefCon: Any?)

    Parameters

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This will ask the server to inform us as to who has access to the given security token.

    Declaration

    Swift

    public func countWhoHasAccessToTheseSecurityTokens(_ inTokens: [Int], refCon inRefCon: Any?)

    Parameters

    inTokens

    An integer array, with the tokens we’re testing.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This will ask the server to get all the logins that have access to provided security token.

    This is security-vetted, so only logins that the current login can see, will be returned.

    Declaration

    Swift

    public func fetchIDsOfLoginsThatHaveThisToken(_ inToken: Int, refCon inRefCon: Any?)

    Parameters

    inToken

    An Integer, with the token we are testing.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This will ask the server to get all the users that have access to provided security token.

    This is security-vetted, so only users that the current login can see, will be returned.

    Declaration

    Swift

    public func fetchIDsOfUsersThatHaveThisToken(_ inToken: Int, refCon inRefCon: Any?)

    Parameters

    inToken

    An Integer, with the token we are testing.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • This method starts a “generic” search, based upon the input given.

    Declaration

    Swift

    public func fetchObjectsUsingCriteria(_ inTagValues: [String : String]? = nil, andLocation inLocation: LocationSpecification! = nil, withPlugin inPlugin: String = "baseline", refCon inRefCon: Any?)

    Parameters

    inTagValues

    This is an optional String-key Dictionary, with the key being any one of these values (on the same line means it must be one of the values). The order is tag, places, people, things: The value must be a String, but, in some cases, it may be a string representation of an integer. The values can use SQL-style wildcards (%) and are case-insensitive. If the object has one of its tags with a matching string (and the user has permission), it may be added to the returned set. Despite the plugin-specific keys, the search will search the tag position of all records, so specifying a givenName of “Billings” will also return any Place object that has a “town” of “Billings”. If this is not specified, or is empty, then all results will be returned. In order to be considered in a location-based search (andLocation is set to a location), then the objects need to have a lat/long value assigned. if a value in inTagValues is an empty String (“”), then the search will search explicitly for objects that do not have a value in that tag. if a value in inTagValues has only a wildcard (“%”), then that means that only objects that have non-empty values of that tag will be returned; regardless of the content of the tag.

                       Possible inTagValues keys are:
                       - "tag0", "venue" (you cannot directly search for the login ID of a user with this method, but you can look for a baseline tag0 value, which is the user login as an Int. Same for thing keys, which are String.)
                       - "tag1", "streetAddress", "surname", "description"
                       - "tag2", "extraInformation", "middleName"
                       - "tag3", "town", "givenName"
                       - "tag4", "county", "nickname"
                       - "tag5", "state", "prefix"
                       - "tag6", "postalCode", "suffix"
                       - "tag7", "nation"
                       - "tag8"
                       - "tag9"
    
    andLocation

    This is a tuple with the following structure: - coords This is a required CLLocationCoordinate2D struct, with a latitude and longitude. - radiusInKm This is a CLLocationDistance (Double) number, with a requested radius (in kilometers). If autoRadiusThreshold is set, and greater than zero, then this is a “maximum” radius. If the auto radius threshold is not specified, this is the full radius. - autoRadiusThreshold This is an optional Int, with a “threshold” number of results to be returned in an “auto-radius hunt.” This means that the SDK will search from the “coords” location, out, in progressively widening circles, until it either gets at least the number in this value, or reaches the maximum radius in “radiusInKm.” If this is specified, the “radiusInKm” specifies the maximum radius to search. At the end of that search, any resources found will be returned, even if they are fewer than requested.

    withPlugin

    This is an optional String. It can specify that only a certain plugin will be searched. For the default plugins, this can only be “baseline”, “people”, “places”, and “things”. If not specified, then the “baseline” plugin will be searched (returns all types).

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • Assigns a personal token to another user.

    Declaration

    Swift

    public func assign(thisPersonalToken inPersonalToken: Int, toThisUserLoginID inUserLoginID: Int, refCon inRefCon: Any?)

    Parameters

    thisPersonalToken

    The ID of the personal token (of the current logged-in user) to assign.

    toThisUserLoginID

    The login ID of the user to which we want to assign the token.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

  • Removes a personal token from another user.

    Declaration

    Swift

    public func remove(thisPersonalToken inPersonalToken: Int, fromThisUserLoginID inUserLoginID: Int, refCon inRefCon: Any?)

    Parameters

    thisPersonalToken

    The ID of the personal token (of the current logged-in user) to remove.

    toThisUserLoginID

    The ID of the user from which we want to remove the token.

    refCon

    This is an optional Any parameter that is simply returned after the call is complete. “refCon” is a very old concept, that stands for “Reference Context.” It allows the caller of an async operation to attach context to a call.

Public Sequence Protocol Conformance

  • Declaration

    Swift

    public func makeIterator() -> RVP_Cocoa_SDK.Iterator

    Return Value

    a new iterator for the instance.