overby.me
this repo has no description
1/*
2 * Copyright (c) 2009 Apple Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24#import <OpenDirectory/OpenDirectory.h>
25
26@class ODQuery;
27@class ODNode;
28
29/*!
30 @protocol ODQueryDelegate
31 @abstract The delegate method for receiving query results from the NSRunLoop-based queries
32 @discussion The delegate method called as results are returned from an NSRunLoop-based query. These results are only partial
33 and delegate is called repeatedly as results are available. The incoming result must be retained or copied. The
34 array will be released by the NSRunLoop upon return. Incoming results do not include previous results,
35 only the most resent results are returned. inResults can be nil if an error occurs or the query is complete. If
36 inResults and inError are nil then the query has completed.
37*/
38@protocol ODQueryDelegate <NSObject>
39@required
40- (void)query:(ODQuery *)inQuery foundResults:(NSArray *)inResults error:(NSError *)inError NS_AVAILABLE(10_6, NA);
41@end
42
43/*!
44 @class ODQuery
45 @abstract Class used for querying OpenDirectory.
46 @discussion OpenDirectory queries may be used to search for different types of records, e.g. users, groups.
47*/
48@interface ODQuery : NSObject <NSCopying>
49{
50 @private
51 void *_internal;
52}
53
54/*!
55 @method queryWithNode:forRecordTypes:attribute:matchType:queryValues:returnAttributes:maximumResults:error:
56 @abstract Creates an autoreleased query with the node using the parameters provided
57 @discussion Creates an autoreleased query with the node using the supplied query parameters. Some parameters
58 can either be NSString or NSData or an NSArray of either NSString or NSData. Passing nil for
59 returnAttributes is equivalent to passing kODAttributeTypeStandardOnly. outError is optional parameter,
60 nil can be passed if error details are not needed.
61*/
62+ (ODQuery *)queryWithNode:(ODNode *)inNode forRecordTypes:(id)inRecordTypeOrList attribute:(ODAttributeType)inAttribute
63 matchType:(ODMatchType)inMatchType queryValues:(id)inQueryValueOrList
64 returnAttributes:(id)inReturnAttributeOrList maximumResults:(NSInteger)inMaximumResults
65 error:(NSError **)outError NS_AVAILABLE(10_6, NA);
66
67/*!
68 @method initWithNode:forRecordTypes:attribute:matchType:queryValues:returnAttributes:maximumResults:error:
69 @abstract Creates a query with the node using the parameters provided
70 @discussion Creates a query with the node using the supplied query parameters. Some parameters
71 can either be NSString or NSData or an NSArray of either NSString or NSData. Passing nil for
72 returnAttributes is equivalent to passing kODAttributeTypeStandardOnly. outError is optional parameter,
73 nil can be passed if error details are not needed.
74*/
75- (instancetype)initWithNode:(ODNode *)inNode forRecordTypes:(id)inRecordTypeOrList attribute:(ODAttributeType)inAttribute
76 matchType:(ODMatchType)inMatchType queryValues:(id)inQueryValueOrList
77 returnAttributes:(id)inReturnAttributeOrList maximumResults:(NSInteger)inMaximumResults error:(NSError **)outError NS_AVAILABLE(10_6, NA);
78
79/*!
80 @method resultsAllowingPartial:error:
81 @abstract Returns results from a provided ODQuery synchronously
82 @discussion Returns results from a provided ODQuery synchronously. Passing NO to inAllowPartialResults
83 will block the call until all results are returned or an error occurs. YES can be passed at any time
84 even if previous calls were made with NO. outError is optional parameter, nil can be passed if error
85 details are not needed.
86*/
87- (NSArray *)resultsAllowingPartial:(BOOL)inAllowPartialResults error:(NSError **)outError NS_AVAILABLE(10_6, NA);
88
89/*!
90 @property delegate
91 @abstract The currently set delegate
92 @discussion The query delegate which will receive asynchronous query results.
93*/
94@property (nonatomic, readwrite, assign) id <ODQueryDelegate> delegate NS_AVAILABLE(10_6, NA);
95
96/*!
97 @method scheduleInRunLoop:forMode:
98 @abstract Adds the query object to the specified NSRunLoop to receive asynchronous results
99 @discussion Adds the query object to the specified NSRunLoop to receive asynchronous results. A delegate must be set
100 in advance otherwise results may be lost due to the lack of a receiver.
101*/
102- (void)scheduleInRunLoop:(NSRunLoop *)inRunLoop forMode:(NSString *)inMode NS_AVAILABLE(10_6, NA);
103
104/*!
105 @method removeFromRunLoop:forMode:
106 @abstract Removes the query object from the specified NSRunLoop
107 @discussion Removes the query object from the specified NSRunLoop.
108*/
109- (void)removeFromRunLoop:(NSRunLoop *)inRunLoop forMode:(NSString *)inMode NS_AVAILABLE(10_6, NA);
110
111/*!
112 @method synchronize
113 @abstract Will dispose of any results and restart the query.
114 @discussion Will dispose of any results and restart the query for subsequent resultsAllowingPartial: calls. If the query
115 is currently scheduled on a RunLoop, then the delegate will be called with inResults == nil and
116 [inError code] == kODErrorQuerySynchronize and [inError domain] == ODFrameworkErrorDomain, signifying that
117 all existing results should be thrown away in preparation for new results.
118*/
119- (void)synchronize NS_AVAILABLE(10_6, NA);
120
121/*!
122 @property operationQueue
123 @abstract The NSOperationQueue on which asynchronous results are delivered to the delegate.
124 @discussion The NSOperationQueue on which asynchronous results are delivered to the delegate.
125 */
126@property (readwrite, retain) NSOperationQueue * operationQueue NS_AVAILABLE(10_6, NA);
127
128@end