| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| #import <Foundation/Foundation.h> |
| #import "UGClientResponse.h" |
| #import "UGQuery.h" |
| #import "UGActivity.h" |
| #import "UGUser.h" |
| |
| /******************** A WORD ON NETWORK COMMUNICATION CALLS **************** |
| Some calls require network communication with UserGrid. Therefore, |
| they all have the option of being synchronous (blocking) or asynchronous. |
| |
| You may specify an asynchronous delegate with the call setDelegate. If you |
| do, all calls will be asynchronous and responses will be sent to that delegate. |
| The immediate return value (a UGClientResponse *) from any call will have its |
| transactionState set to kUGClientResponsePending, and the transactionID will be |
| properly set (allowing you to identify the specific call in your callback if you |
| wish.) |
| |
| The delegate must support the following message: |
| -(void)ugClientResponse:(UGClientResponse *)response |
| |
| If you do not set a delegate, all functions will run synchronously, blocking |
| until a response has been received or an error detected. |
| ****************************************************************************/ |
| |
| |
| /**************************** A WORD ON UGQUERY ***************************** |
| Some calls take a UGQuery *. These are functions that return a lot of data, as |
| opposed to a simple answer. You may use the UGQuery to control the data with filters |
| and response limits. See UGQuery.h for more information. |
| |
| In all cases, where a UGQuery is one of the parameters, you may send nil. If you |
| do, the query will be completely unfiltered, and you will receive back *all* the data |
| associated with the operation, up to the response limit, which is 10. You can |
| set the response limit in UGQuery as well. |
| ****************************************************************************/ |
| |
| |
| @interface UGClient : NSObject |
| |
| +(NSString *) version; |
| |
| /********************* INIT AND SETUP *********************/ |
| // init with an app ID |
| -(id) initWithOrganizationId: (NSString *)organizationID withApplicationID:(NSString *)applicationID; |
| |
| // init with an app ID and a base UserGrid URL. This is useful if you |
| // are running a local UG server or your company has its own public |
| // UG server. The default URL is http://api.usergrid.com. The base URL |
| // must be a fully formated http link, including the "http://" at the |
| // beginning. |
| -(id) initWithOrganizationId: (NSString *)organizationID withApplicationID:(NSString *)applicationID baseURL:(NSString *)baseURL; |
| |
| // set the delegate. See "A WORD ON NETWORK COMMUNICATION CALLS" |
| // at the top of the file for a detailed explanation. The function |
| // will return NO if the delegate is rejected. This means the delegate |
| // does not support the required delegation function "ugClientResponse". |
| // |
| // This is the formal declaration of ugClientResponse: |
| // -(void)ugClientResponse:(UGClientResponse *)response |
| // |
| // You may change the delegate at any time, but be forewarned that any |
| // pending transactions in progress will be abandoned. Changing the delegate |
| // (especially setting it to nil) ensures that hte previous delegate will |
| // receive no further messages from this instance of UGClient. |
| // |
| // Setting the delegate to nil puts the API in to synchronous mode. |
| -(BOOL) setDelegate:(id)delegate; |
| |
| |
| /********************* LOGIN / LOGOUT *********************/ |
| // log in with the given username and password |
| -(UGClientResponse *)logInUser: (NSString *)userName password:(NSString *)password; |
| |
| // log in with the given username and PIN value |
| -(UGClientResponse *)logInUserWithPin: (NSString *)userName pin:(NSString *)pin; |
| |
| // log in user with Facebook token |
| // |
| // //sample usage: |
| // NSString * facebookToken = @"your-facebook-token"; |
| // UGClientResponse *response = [usergridClient logInUserWithFacebook:facebookToken]; |
| // user = [usergridClient getLoggedInUser]; |
| // if (user.username){ |
| // return true; |
| // } else { |
| // return false; |
| // } |
| // |
| -(UGClientResponse *)logInUserWithFacebook: (NSString *)facebookToken; |
| |
| // log in as the administrator of the application. Generally used for applications |
| // that have an "administrator" feature. Not the sort of thing you want normal |
| // users doing. |
| -(UGClientResponse *)logInAdmin: (NSString *)adminUserName secret:(NSString *)adminSecret; |
| |
| // log out the current user. The Client only supports one user logged in at a time. |
| // You can have multiple instances of UGClient if you want multiple |
| // users doing transactions simultaneously. This does not require network communication, |
| // so it has no return. It doesn't actually "log out" from the server. It simply clears |
| // the locally stored auth information |
| -(void)logOut; |
| |
| |
| |
| /********************* USER MANAGEMENT *********************/ |
| //adds a new user |
| -(UGClientResponse *)addUser:(NSString *)username email:(NSString *)email name:(NSString *)name password:(NSString *)password; |
| |
| // updates a user's password |
| -(UGClientResponse *)updateUserPassword:(NSString *)usernameOrEmail oldPassword:(NSString *)oldPassword newPassword:(NSString *)newPassword; |
| |
| // get all the groups this user is in |
| -(UGClientResponse *)getGroupsForUser: (NSString *)userID; |
| |
| // get users in this app. Definitely want to consider sending a Query along |
| // with this call |
| -(UGClientResponse *)getUsers: (UGQuery *)query; |
| |
| /********************* ACTIVITY MANAGEMENT *********************/ |
| // create a new activity. |
| // Note that there is a class, UGActivity, which can help |
| // you create and validate an Activity, and will generate the needed |
| // NSDictionary for you. |
| -(UGClientResponse *)createActivity: (NSDictionary *)activity; |
| |
| // create an activity and post it to a user in a single step. See comment |
| // above createActivity for information on making Activity creation easier |
| -(UGClientResponse *)postUserActivity: (NSString *)userID activity:(NSDictionary *)activity; |
| |
| // post an already-created activity to a user |
| -(UGClientResponse *)postUserActivityByUUID: (NSString *)userID activity:(NSString *)activityUUID; |
| |
| // create an activity and post it to a group in a single step. See comment |
| // above createActivity for information on making Activity creation easier |
| -(UGClientResponse *)postGroupActivity: (NSString *)groupID activity:(NSDictionary *)activity; |
| |
| // post an already-created activity to a group |
| -(UGClientResponse *)postGroupActivityByUUID: (NSString *)groupID activity:(NSString *)activityUUID; |
| |
| // get the activities this user is in |
| -(UGClientResponse *)getActivitiesForUser: (NSString *)userID query:(UGQuery *)query; |
| |
| // get the activities this group is in |
| -(UGClientResponse *)getActivitiesForGroup: (NSString *)groupID query:(UGQuery *)query; |
| |
| // get the activity feed for a user |
| -(UGClientResponse *)getActivityFeedForUser: (NSString *)userID query:(UGQuery *)query; |
| |
| // get the activity feed for a group |
| -(UGClientResponse *)getActivityFeedForGroup: (NSString *)groupID query:(UGQuery *)query; |
| |
| // remove an activity |
| -(UGClientResponse *)removeActivity:(NSString *)activityUUID; |
| |
| /********************* GROUP MANAGEMENT *********************/ |
| // create a new group. The groupPath can be a path with slashes to make for |
| // a hierarchical structure of your own design (if you want). groupTitle is |
| // optional, you can send nil if you don't want to provide one. |
| -(UGClientResponse *)createGroup:(NSString *)groupPath groupTitle:(NSString *)groupTitle; |
| |
| // add a user to a group |
| -(UGClientResponse *)addUserToGroup:(NSString *)userID group:(NSString *)groupID; |
| |
| // remove a user from a group |
| -(UGClientResponse *)removeUserFromGroup:(NSString *)userID group:(NSString *)groupID; |
| |
| // get all the users in this group |
| -(UGClientResponse *)getUsersForGroup:(NSString *)groupID query:(UGQuery *)query; |
| |
| |
| |
| /******************** ENTITY MANAGEMENT ********************/ |
| // adds an entity to the specified collection. |
| -(UGClientResponse *)createEntity: (NSDictionary *)newEntity; |
| |
| // get a list of entities that meet the specified query. |
| -(UGClientResponse *)getEntities: (NSString *)type query:(UGQuery *)query; |
| |
| // updates an entity (it knows the type from the entity data) |
| -(UGClientResponse *)updateEntity: (NSString *)entityID entity:(NSDictionary *)updatedEntity; |
| |
| // removes an entity of the specified type |
| -(UGClientResponse *)removeEntity: (NSString *)type entityID:(NSString *)entityID; |
| |
| // Directionally connect two entities. For instance, user "Bob" might like Lyons Restaurant. |
| // connectorType would be "users" (because Bob is a user) |
| // connectorID would be Bob's userID |
| // connectionType would be "like" |
| // connecteeID would be the UUID of Lyons Restaurant |
| -(UGClientResponse *)connectEntities: (NSString *)connectorType connectorID:(NSString *)connectorID type:(NSString *)connectionType connecteeID:(NSString *)connecteeID; |
| |
| // Directionally connect two entities. For instance, user "Bob" might follow user "Mary". |
| // connectorType would be "users" (because Bob is a user) |
| // connectorID would be Bob's userID |
| // connectionType would be "like" |
| // connecteeType would be "users" (because Mary is a user) |
| // connecteeID would be Mary's userID |
| -(UGClientResponse *)connectEntities: (NSString *)connectorType connectorID:(NSString *)connectorID connectionType:(NSString *)connectionType connecteeType:(NSString *)connecteeType connecteeID:(NSString *)connecteeID; |
| |
| // disconnect two entities. It uses the same parameters and calling rules as connectEntities |
| -(UGClientResponse *)disconnectEntities: (NSString *)connectorType connectorID:(NSString *)connectorID type:(NSString *)connectionType connecteeID:(NSString *)connecteeID; |
| |
| // get entity connections |
| -(UGClientResponse *)getEntityConnections: (NSString *)connectorType connectorID:(NSString *)connectorID connectionType:(NSString *)connectionType query:(UGQuery *)query; |
| |
| |
| |
| /********************* MESSAGE MANAGEMENT *********************/ |
| // post a message to a given queue |
| -(UGClientResponse *)postMessage: (NSString *)queuePath message:(NSDictionary *)message; |
| |
| // get all messages from the queue path |
| -(UGClientResponse *)getMessages: (NSString *)queuePath query:(UGQuery *)query; |
| |
| // add a subscriber to a queue |
| -(UGClientResponse *)addSubscriber: (NSString *)queuePath subscriberPath:(NSString *)subscriberPath; |
| |
| // remove a subscriber from a queue |
| -(UGClientResponse *)removeSubscriber: (NSString *)queuePath subscriberPath:(NSString *)subscriberPath; |
| |
| |
| /********************* SERVER-SIDE STORAGE *********************/ |
| // these functions refer to data that can be put in a special place |
| // specific to this device. Every call to remoteStorage replaces whatever |
| // was there before |
| |
| // put the data in to the remote storage |
| -(UGClientResponse *)setRemoteStorage: (NSDictionary *)data; |
| |
| // get the data from remote storage |
| -(UGClientResponse *)getRemoteStorage; |
| |
| // a class function that returns a uuid for this |
| // device. It will be globally unique, and will always |
| // return the same value for the same handset. |
| // NOTE - This value will change if the operating |
| // system is reinstalled. This function is used internally, but |
| // is also handy for clients, so it is part of the interface. |
| +(NSString *)getUniqueDeviceID; |
| |
| /***************** REMOTE PUSH NOTIFICATIONS *****************/ |
| |
| // call from application:didRegisterForRemoteNotificationsWithDeviceToken: callback |
| // will automatically register the passed deviceToken with the usergrid system |
| // using the getUniqueDeviceID method to associate this device on the server |
| - (UGClientResponse *)setDevicePushToken:(NSData *)newDeviceToken forNotifier:(NSString *)notifier; |
| |
| // push an "alert" type notification to the remote group, user, or device specified |
| // in the path argument. the notifer may be a name or UUID of an apns notifier |
| // that has been set up on the usergrid server. |
| - (UGClientResponse *)pushAlert:(NSString *)message |
| withSound:(NSString *)sound |
| to:(NSString *)path |
| usingNotifier:(NSString *)notifier; |
| |
| /*********************** ACCESSORS ************************/ |
| // if a user is logged in, this returns the OAuth token for this session. |
| // UGClient manages this internally, so you never really need it. But if you |
| // want it for other reasons, this accessor gives it to you. If you have not |
| // successfully logged in, this will return nil |
| -(NSString *)getAccessToken; |
| |
| // returns information about the logged in user |
| -(UGUser *)getLoggedInUser; |
| |
| // returns the delegate that is currently being used for asynch |
| // calls. Returns nil if there is no delegate (synch mode) |
| -(id) getDelegate; |
| |
| /*********************** OBLIQUE USAGE ************************/ |
| // This is a general purpose function for directly accessing the |
| // UserGrid service. This is useful if the service has new features |
| // that the API has not yet supported, or if you are using an older |
| // version of the API and don't want to upgrade. |
| // |
| // url: The full URL that you are accessing. You are responsible for |
| // assembling it, including the appID and all sub-sections down the line |
| // |
| // op: The HttpMethod being invoked. Examples: @"POST", @"PUT", etc. You may |
| // send nil. If you do, the operation is GET. There is one specially supported |
| // method called "POSTFORM". This will post with the data type set to |
| // application/x-www-form-urlencoded instead of the more likely needed |
| // application/json. This is necessary if you are doing authentication |
| // or if you are sending form data up. |
| // |
| // opData: The data sent along with the operation. You may send nil. If the |
| // operation is GET, this value is ignored. Usually, this would be |
| // expected to be in json format. With this oblique approach, it is |
| // your responsibility to format the data correctly for whatever you're |
| // doing. Bear in mind that this api comes with SBJson, which provides |
| // some very simple ways to assemble json formatted strings. See SBJsonWriter. |
| // |
| // NOTE - This function will be synchronous or asynchronous the same as any |
| // other function in the API. It is based on the value sent to setDelegate. |
| -(UGClientResponse *)apiRequest: (NSString *)url operation:(NSString *)op data:(NSString *)opData; |
| |
| /*********************** DEBUGGING ASSISTANCE ************************/ |
| // when logging is on, all outgoing URLs are logged via NSLog, and all |
| // incoming data from the service is also logged. Additionally, any errors |
| // encountered internally are logged. This can be helpful to see the actual |
| // service communication in progress and help debug problems you may be having. |
| -(void)setLogging: (BOOL)loggingState; |
| |
| /*********************** VERSION CHECKING ************************/ |
| #define SYSTEM_VERSION_EQUAL_TO(v) ([[[UIDevice currentDevice] systemVersion] compare:v options:NSNumericSearch] == NSOrderedSame) |
| #define SYSTEM_VERSION_GREATER_THAN(v) ([[[UIDevice currentDevice] systemVersion] compare:v options:NSNumericSearch] == NSOrderedDescending) |
| #define SYSTEM_VERSION_GREATER_THAN_OR_EQUAL_TO(v) ([[[UIDevice currentDevice] systemVersion] compare:v options:NSNumericSearch] != NSOrderedAscending) |
| #define SYSTEM_VERSION_LESS_THAN(v) ([[[UIDevice currentDevice] systemVersion] compare:v options:NSNumericSearch] == NSOrderedAscending) |
| #define SYSTEM_VERSION_LESS_THAN_OR_EQUAL_TO(v) ([[[UIDevice currentDevice] systemVersion] compare:v options:NSNumericSearch] != NSOrderedDescending) |
| |
| @end |