DB_API_Documentation.txt

DATABASE API DOCUMENTATION
       FOR THE
   EVENT HANDLER APP


###########################
#       Created by        #
#   Malcolm Geldmacher    #
#           For           # 
#       Vient Apps        #
###########################

TABLE OF CONTENTS:
1. Flow Diagram
2. Standardization
3. List of available Functions
4. Definitions of available Functions






##############################
#         CHAPTER 1          #
#        FLOW DIAGRAM        #
##############################

The flow of code is as follows:

----------------------------------------------------------------------------
On app creation, a global db object is created
                    |
                    V
User completes action in app that requires db crud
                    |
                    V
Event handler code for action calls appropriate method of global db object and passes any necessary parameters
                    |
                    V
db object method creates httprequest and calls appropriate url/php script with necessary url parameters
                    |
                    V
server php script uses url parameters to call the associated stored procedure from the server through phpmyadmin/mysqli functionality
                    |
                    V
stored procedure on server db executes with parameters and returns results to php script
                    |
                    V
php script interprets results and returns a json string as appropriate.
                    |
                    V
db object in app collects and objectifies the json string into the appropriate object and returns said object to the calling code.
---------------------------------------------------------------------------






##############################
#         CHAPTER 2          #
#      STANDARDIZATION       #
##############################

In order to standardize all output from the httpRequests, the following standardization has been made:

All php scripts return the following JSON object:
{
	response : (either "error", "failure", or "success"),
	message : (message related to action performed and response),
	result : [(array of result objects from the database if appropriate)]
}







##############################
#         CHAPTER 3          #
#          LIST OF           #
#    AVAILABLE FUNCTIONS     #
##############################

Here is a list of all available functions. Please see Chapter 4 for more detailed information about each of these functions including return types, parameters, return codes, etc.

------------------------
login
getEventsByLocation
createEvent







##############################
#         CHAPTER 4          #
#      DEFINITIONS OF        #
#    AVAILABLE FUNCTIONS     #
##############################

This chapter contains detailed definitions and specifications of how the available functions in chapter 3 work. Descriptions will include return values, expected parameters and any other pertinent information to programming with these funcitons.

The programmer should know that there is a dbErr variable of the Database class that will give added information about any unsuccessful attempts at any queries.Those values will be specific to the function being called.



*************
**  login  **
*************

DESCRIPTION:
    The login function should be used when a user of the system is attempting to log in to their account. Using the results of the login function will allow the programmer to know if the login was successful or not and doubles as a getUser function on successful login.

PARAMETERS:
    username: String
    password: String

RETURN VALUES:
    If the login is successful, meaning that a correct password was given with the corresponding username, a User object is returned from the login function populated with all the user information from the database, excluding the password.
    When a login is unsuccessful, the login function returns nil.

DBERR CODES:
    0: Successful login
    1: Unsuccessful login(mismatched username/password combination)
    2: Connection/Query error

 

***************************
**  getEventsByLocation  **
***************************

DESCRIPTION:
    The getEventsByLocation function returns an array of Event objects that are located within a specified range in miles given a specific location.

PARAMETERS:
    location: Location
    range: Double

RETURN VALUES:
    If there are no query errors or connection errors, the function returns an array of Event objects that are within the given range of the specified location.
    In the case of some error, the function returns nil.

DBERR CODES:
    0: Successful query
    1: N/A
    2: Connection/Query error



*******************
**  createEvent  **
*******************

DESCRIPTION:
    The createEvent function creates an Event with the given parameters and stores it in the database.

PARAMETERS:
    userId: Int
    title: String
    description: String
    date: DateTime
    duration: Int
    location: Location
    private: Bool
    maxAttendance: Int
    minRating: Double

RETURN VALUES:
    The function returns a fully populated Event object in the case of a successful Event creation/storage in the database.
    In the case of some error, the function returns nil.

DBERR CODES:
    0: Successful query
    1: N/A
    2: Connection/Query error