RVP_Cocoa_SDK

public class RVP_Cocoa_SDK : NSObject, Sequence, URLSessionDelegate

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.

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

    Declaration

    Swift

    public struct HTTPError : Error
  • 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
  • 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 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 }
  • 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 }
  • 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?
  • 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: TimeInterval! = nil, session inURLSession: URLSession? = nil)

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

    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.

  • 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])

    Parameters

    inItemArray

    An Array of concrete instances of subclasses of A_RVP_IOS_SDK_Object.

  • 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: TimeInterval! = nil)

    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.

  • 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: TimeInterval)

    Parameters

    loginID

    (REQUIRED) A String, with a login ID.

    password

    (REQUIRED) A String, with a login password.

    timeout

    (REQUIRED) A Floating-point value, with the number of seconds the login has to be active.

  • 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()
  • This simply empties our cache, forcing the next load to go out to the server.

    Declaration

    Swift

    public func flushCache()
  • The way that this works, is that the main app calls createUserLoginPair(loginString:,name:), and a semaphore is set. The SDK then attempts to create the login object. If that is successful, then it will continue, and create the user object to accompany the new login object, after informing the delegate of the new login object, but will not be called with the sdkInstance(_:,fetchedDataItems:) call. If the login object creation fails, the main app delegate will be called with an error. If it is successful, the delegate is then called with the new user object. This will create a completely bald set of objects, with only the login ID, name, and default security tokens. This can only be called if you are logged in as a manager.

    Declaration

    Swift

    public func createUserLoginPair(loginString inLoginStringID: String, name inName: String = "")

    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.

  • 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", dontNukeTheLocation inDontNuke: Bool = false)

    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.

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

    Declaration

    Swift

    public func fetchBaselineObjectsByID(_ inIDArray: [Int])

    Parameters

    inIDArray

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

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

    Declaration

    Swift

    public func fetchPlaces(_ inPlaceIDArray: [Int])

    Parameters

    inPlaceIDArray

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

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

    Declaration

    Swift

    public func fetchUsers(_ inUserIntegerIDArray: [Int])

    Parameters

    inUserIntegerIDArray

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

  • This fetches thing objects from the data database server.

    Declaration

    Swift

    public func fetchThings(_ inThingIntegerIDArray: [Int])

    Parameters

    inThingIntegerIDArray

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

  • This fetches thing objects from the data database server.

    Declaration

    Swift

    public func fetchThings(_ inKeys: [String])

    Parameters

    inKeys

    An Array of String, with the thing keys.

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

    Declaration

    Swift

    public func fetchLogins(_ inLoginIntegerIDArray: [Int])

    Parameters

    inLoginIntegerIDArray

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

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

    Declaration

    Swift

    public func fetchLogins(_ inLoginStringIDArray: [String])

    Parameters

    inLoginStringIDArray

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

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

    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

    Declaration

    Swift

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

    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.

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

  • Declaration

    Swift

    public func makeIterator() -> RVP_Cocoa_SDK.Iterator

    Return Value

    a new iterator for the instance.