MSFramework

An iOS framework for communicating with Web MySQL databases with POST and JSON

Download latest release
Repository

Features

  • Supports POST over HTTP/S with/without protected directories
  • Features internal CoreData manager with an exposed NSManagedObjectContext for manipulating CoreData yourself
  • Includes robust AES-256 bit encryption & Hashing+Salting
  • Self-contained SQL wrapper that prevents SQL overloading and injection
  • Framework format for easy API usage and understanding
  • Swift 4 support

API Guide

MSFrameworkDataSource

The protocol an object must implement in order for MSFramework to properly communicate with the web service

  • website: The base URL the application will be communicating with

  • readFile: The relative path to a file in the URL that takes a POST object containing`databaseUserPass, websiteUserName, and an SQL statement and returns a JSON formatted object.
    This file should take in three parameters for the POST:
    • Password
    • Username
    • SQLStatement

  • writeFile: The relative path to a file in the URL that takes a POST object containing databaseUserPass, websiteUserName, and an SQL statement and processes the SQL statement returning "Success" if the SQLStatement is successfully ran or "Failure" if it fails
    This file should take in three parameters for the POST:
    • Password
    • Username
    • SQLStatement

  • websiteUserName: The username to log into a protected directory. This value is only used if needed.

  • websiteUserPass: The password to log into a protected directory. This value is only used if needed.

  • databaseUserPass: MySQL databases require user login and password to access the databse schema. MSFramework assumes the login websiteUserName combined with this password

  • coreDataModelName: The file name of your project's CoreData model

  • encryptionCode: A String containing 32 characters ([A-Za-z0-9] & special characters) that is used to encrypt and decrypt data on device

  • iv: The initialization vector for MSFramework's encryption

The main class through which the API is levereged

Framework Variables
  • public typealias MSFrameworkDownloadCompletion = (_ returnData: [Any]?,_ error: Error?) -> Void
    The download Completion Handler
    Parameters
    • returnData: The returned JSON Serialized data. This data is usually an array of Dictionaries
    • error: An error when downloaded, if any

  • public typealias MSFrameworkUploadCompletion = (_ success: Bool) -> Void
    The upload Completion Handler
    Parameters
    • success: Whether the upload failed or succeeded
Framework Methods
  • public func saveCoreData() throws
    Quick saving CoreData
General
  • public let dataDownloader : MSDataDownloader
    The Data Downloader object for MSFramework

  • public let dataUploader : MSDataUploader
    The Data Uploader object for MSFramework

  • public var dataSource : MSFrameworkDataSource!
    The data source for MSFramework contains all necessary information for MSFramework to communicate with your application's web service

  • public var managedObjectContext : NSManagedObjectContext?
    MSFramework's current NSManagedObjectContext object. Returns nil if the Persistent Store hasn't finished loading yet

  • public static let `default` : MSFrameworkManager
    Grabs the singleton object of MSFrameworkManager

  • public func enableDebug()
    Call this method to enable debugging mode
Encryption / Decryption
  • public func encrypt(string: String) -> String
    Encrypts a string using an AES 256-bit algorithm
    Parameters
    • string: A plain text string
    Returns
    • The HEX representation from an AES 256-bit encrypted object

  • public func encrypt(object: Any) -> String
    Encrypts an object using an AES 256-bit algorithm
    Parameters
    • object: An NSObject (Any in Swift) object
    Returns
    • The HEX representation from an AES 256-bit encrypted object

  • public func decrypt(string: String) -> String
    Decrypts an AES 256-bit encrypted string
    Parameters
    • string: The HEX String returned from encrypt(string:)
    Returns
    • The HEX representation from an AES 256-bit encrypted object

  • public func decrypt(object: String) -> Any?
    Decrypts an AES 256-bit encrypted object
    Parameters
    • object: The HEX String returned from encrypt(object:)
    Returns
    • A decrypted object or nil if the string isn't an encrypted object
Other
  • public func retrieveList(attribute: String, onEntity entity: String) -> [Any]
    Conveience method to list all the entities' values of an attribute for the entity name. Searches only on-device stored data
    Parameters
    • attribute: The attribute to recall values from
    • entity: The entity name to search in
    Returns
    • A list of values across all instances of entity for that attribute

The data downloader class
MSDataDownloader connects to a URL, sends a POST request, downloads JSON formatted data, then converts that data into an NSArray and returns it via a completionHandler

  • public func download(sqlStatement: MSSQL, completion: @escaping MSFrameworkDownloadCompletion)
    Downloads JSON formatted data from website+readFile
    This method will return control to your application immediately, deferring call back to completion. completion will always be ran on the main thread
    Parameters
    • sqlStatement: An MSSQL object that contains a built SQL statement
    • completion: A block to be called when all data has been downloaded

The data uploader class
MSDataUploader connects to a URL, sends a POST request containing the SQL statement to run, downloads Success or Failure, and calls completion with a Bool parameter based upon that

  • public func upload(sqlStatement: MSSQL, completion: @escaping MSFrameworkUploadCompletion)
    Uploads an SQL statement to website+writeFile
    This method will return control to your application immediately, deferring call back to completion. completion will always be ran on the main thread
    Parameters
    • sqlStatement: An MSSQL object that contains a built SQL statement
    • completion: A block to be called when returned either Success or Failure

An SQL wrapper that provides security, overload safety, and sanitization

Framework Enums
  • public enum MSSQLError : Error
    An enum of throwable errors

  • public enum MSSQLConjunction : String
    An enum of possible conjunctions to use with JOIN and WHERE

  • public enum MSSQLJoin : String
    An enum of the supported JOIN types

  • public enum MSSQLEquivalence : String
    An enum of possible equivelence operators
Framework Structs
  • public struct MSSQLClause
    A struct that represents an XX=XX clause

  • public struct Join
    A struct that reprents a JOIN `XXXX` ON XX=XX clause

  • public struct Where
    A struct representing a WHERE XX=XX clause

General
  • public func append(_ sqlStatement : MSSQL)
    Appends an MSSQL object to the current MSSQL object
    Parameters
    • sqlStatement: An MSSQL object. Immutable once placed in the list
    Returns
    • An instance of MSSQL
SELECT ...
  • public func select(_ attribute: String) throws -> MSSQL
    SELECT statement with 1 row
    Parameters
    • attribute: the attribute to request
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If no attribute specified, * is used, is empty, or if attribute is greater than 64 characters in length

  • public func select(_ attributes: [String]) throws -> MSSQL
    SELECT statement with multiple rows
    Parameters
    • attributes: the attributes to request
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If no attributes specified, * is used, any attribute in attributes is empty, or if any attribute in attributes is greater than 64 characters in length
FROM ...
  • public func from(_ table: String) throws -> MSSQL
    FROM statement with one table
    Parameters
    • table: the table to query
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If no table specified, * is used, if table is empty, or if table is greater than 64 characters in length

  • public func from(_ tables: [String]) throws -> MSSQL
    FROM statement with multiple tables
    Parameters
    • tables: the tables to query
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If no tables specified, * is used, any table in tables is empty, or if any table in tables is greater than 64 characters in length
UPDATE ... SET
  • public func update(_ table: String, leftHandSide: String, rightHandSide: String) throws -> MSSQL
    UPDATE statement with one clause
    Parameters
    • table: the table to query
    • leftHandSide: the left hand side of the clause
    • rightHandSide: the right hand side of the clause
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If a parameter is nil, already exists, * is used, is empty, or table | leftHandSide is greater than 64 characters in length

  • public func update(_ table: String, set clauses: [MSSQLClause]) throws -> MSSQL
    UPDATE statements with multiple clauses
    Parameters
    • tables: the tables to query
    • clauses: The clauses
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If a parameter is nil, already exists, * is used, is empty, or the table | leftHandSide of any clause is greater than 64 characters in length
INSERT INTO ...
  • public func insert(_ table: String, values: [String], attributes: [String]) throws -> MSSQL
    INSERT INTO statement
    Parameters
    • table: the table to insert the new row into
    • values: the values for entry
    • attributes: the attributes to set
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If a parameter is null, already exists, values and attributes do not match in size, * is used, is empty, or table | any attribute in attributes is greater than 64 characters in length
JOIN ... ON
  • public func join(_ join: MSSQLJoin, table: String, leftHandSide: String, rightHandSide: String) throws -> MSSQL
    JOIN statement with one clause
    Parameters
    • table: the table to query
    • leftHandSide: the left hand side of the clause
    • rightHandSide: the right hand side of the clause
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If a parameter is nil, already exists, * is used, is empty, or table | leftHandSide is greater than 64 characters in length

  • public func join(_ join: MSSQLJoin, joins: [Join]) throws -> MSSQL
    Multiple JOIN statements
    Parameters
    • join: the type of join
    • joins: The joins to make
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If a parameter is null, already exists, * is used, is empty, or if the table | leftHandSide of any Join is greater than 64 characters in length
WHERE
  • public func `where`(_ equivalence: MSSQLEquivalence, leftHandSide: String, rightHandSide: String) throws -> MSSQL
    WHERE ...X... statement
    Parameters
    • equivalence: The equivalence of the statement
    • leftHandSide: the left hand side of the clause
    • rightHandSide: the right hand side of the clause
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If a parameter is nil, already exists, * is used, is empty, or leftHandSide is greater than 64 characters in length

  • public func `where`(_ `where`: MSSQLConjunction, equivalence: MSSQLEquivalence, leftHandSides: [String], rightHandSides: [String]) throws -> MSSQL
    WHERE ...X...[, ...X...] statement
    Parameters
    • `where`: The conjunction to use when joining successive WHERE statements
    • equivalence: The equivalence of each statement
    • leftHandSides: The left hand sides of the clauses
    • rightHandSides: The right hand sides of the clauses
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If a parameter is nil, already exists, * is used, is empty, or if any leftHandSide in leftHandSides is greater than 64 characters in length
  • public func `where`(custom: [Where]) throws -> MSSQL
    WHERE ...X...[, ...Y...] statement
    Parameters
    • custom: A collection of Where structs. The last Where struct MUST have .none as the conjunction
    Returns
    • An instance of MSSQL
    Throws
    • MSSQLError: If a parameter is null, already exists, * is used as the leftHandSide parameter of any Where, any parameter is empty, any leftHandSide is greater than 64 characters in length, or if the last Where struct does not have .none as its conjunction

© 2017 Michael Schloss. All rights reserved.