sdks/ios/UGAPI/UGQuery.h

/*
 * 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 <CoreLocation/CoreLocation.h>

enum
{
    kUGQueryOperationEquals = 0,
    kUGQueryOperationLessThan = 1,
    kUGQueryOperationLessThanOrEqualTo = 2,
    kUGQueryOperationGreaterThan = 3,
    kUGQueryOperationGreaterThanOrEqualTo = 4
};

/***************************************************************
 QUERY MANAGEMENT:
 
 All query functions take one of these as an optional parameter
 (the client may send nil if desired). This will specify the
 limitations of the query. 
***************************************************************/

@interface UGQuery : NSObject

// url terms used in UG searches. Set as you like.
// These are convenience methods. the same effect can be done
// by calling addURLTerm
-(void)setConsumer: (NSString *)consumer;
-(void)setLastUUID: (NSString *)lastUUID;
-(void)setTime: (long)time;
-(void)setPrev: (int)prev;
-(void)setNext: (int)next;
-(void)setLimit: (int)limit;
-(void)setPos: (NSString *)pos;
-(void)setUpdate: (BOOL)update;
-(void)setSynchronized: (BOOL)synchronized;

// a general function for adding additional URL terms.
// Note that all of the set functions above turn around and
// call this.
-(void)addURLTerm: (NSString *)urlTerm equals:(NSString *)equals;

// ql operation requirements. For each of these, you provide the term, followed 
// by the operation (a kUGQueryOperationXXXX constant) followed by the value
// in whatever form you have it (NSString, int, or float are supported)
// Example: [foo addRequiredOperation: @"age" kUGQueryLessThan valueInt:27] would
// add the term "age < 27" to the ql.
-(void)addRequiredOperation: (NSString *)term op:(int)op valueStr:(NSString *)valueStr;
-(void)addRequiredOperation: (NSString *)term op:(int)op valueInt:(int) valueInt;

// adds a "contains" requirement to the query. This adds the requirement that a value
// contain a given string. Example: [foo addRequiredContains:@"hobbies value:@"fishing"]
// would add the term "hobbies contains 'fishing'" to the ql.
-(void)addRequiredContains: (NSString *)term value:(NSString *)value;

// adds an "in" requirement to the query. This adds a requirement that a field
// be within a certain range. Example [foo appendRequiredIn:@"age" low:16.0 high:22.0]
// would add the term "age in 16.0,22.0" to the ql. 
// Note that the qualifier is inclusive, meaning it is true if low <= term <= high. 
-(void)addRequiredIn:(NSString *)term low:(int)low high:(int)high;

// adds a "within" requirement. This adds a constraint that the term be within a 
// certain distance of the sent-in x,y coordinates.
-(void)addRequiredWithin:(NSString *)term latitude:(float)latitude longitude:(float)longitude distance:(float)distance;

// assembles a "within" requirement with a term name, CLLocation, and distance
-(void)addRequiredWithinLocation:(NSString *)term location:(CLLocation *)location distance:(float)distance;

//-------------------- Oblique usage ----------------------------
// adds a requirement to the query. The requirements will
// *all* be sent when the query is adopted. This is an escalating
// list as you add them. Requirements are in UG Querty language.
// So something like "firstname='bob'". This is one of the few places
// where the data you give will be sent to the server almost untouched. 
// So if you make a mistake in your query, you are likely to cause the whole
// transaction to return an error. 
// NOTE: This is different thant URL terms. These are query terms sent along
// to the *single* URL term "ql". 
// Note: This is an oblique-usage function. You will find all the ql operations
// supported in the various addRequiredXXXX functions above. You would only use
// this function if you already have ql strings prepared for some reason, or if
// there are new ql format operations that are not supported by this API.
-(void)addRequirement: (NSString *)requirement;

// returns the URL-ready string that detailes all specified requirements.
// This is used internally by UGClient, you don't need to call it.
-(NSString *)getURLAppend;

@end