overby.me
this repo has no description
1/*
2 * Copyright (c) 2005-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 ODConfiguration;
27@class ODRecord;
28
29/*!
30 @class ODNode
31 @abstract This class is used to work with OpenDirectory nodes.
32 @discussion OpenDirectory uses nodes to represent different sources of directory information, via the local disk, LDAP, etc.
33*/
34@interface ODNode : NSObject {
35 @private
36 void *_internal;
37}
38
39/*!
40 @method nodeWithSession:type:error:
41 @abstract Create an autoreleased ODNode of the given type, optionally in a specific session.
42 @discussion Autoreleased instance of an ODNode with a provided ODSession and ODNodeType. outError is
43 optional parameter, nil can be passed if error details are not needed.
44*/
45+ (instancetype)nodeWithSession:(ODSession *)inSession type:(ODNodeType)inType error:(NSError **)outError NS_AVAILABLE(10_6, NA);
46
47/*!
48 @method nodeWithSession:name:error:
49 @abstract Create an autoreleased ODNode with the given name, optionally in a specific session.
50 @discussion autoreleased instance of an ODNode with a provided ODSession and node name. outError is
51 optional parameter, nil can be passed if error details are not needed.
52*/
53+ (instancetype)nodeWithSession:(ODSession *)inSession name:(NSString *)inName error:(NSError **)outError NS_AVAILABLE(10_6, NA);
54
55/*!
56 @method initWithSession:type:error:
57 @abstract Initialize an ODNode instance of the given type, optionally in a specific session.
58 @discussion initialize instance of an ODNode with a provided ODSession and ODNodeType. outError is
59 optional parameter, nil can be passed if error details are not needed.
60*/
61- (instancetype)initWithSession:(ODSession *)inSession type:(ODNodeType)inType error:(NSError **)outError NS_AVAILABLE(10_6, NA);
62
63/*!
64 @method initWithSession:name:error:
65 @abstract Initialize an ODNode instance with the given name, optionally in a specific session.
66 @discussion initialize instance of an ODNode with a provided ODSession and node name. outError is optional
67 parameter, nil can be passed if error details are not needed.
68*/
69- (instancetype)initWithSession:(ODSession *)inSession name:(NSString *)inName error:(NSError **)outError NS_AVAILABLE(10_6, NA);
70
71/*!
72 @method subnodeNamesAndReturnError:
73 @abstract Returns NSArray of node names for this node, which may contain sub-nodes or search policy nodes
74 @discussion Returns NSArray of node names for this node, which may contain sub-nodes or search policy nodes.
75 Commonly used with Search policy nodes. outError is optional parameter, nil can be passed if error
76 details are not needed.
77*/
78- (NSArray *)subnodeNamesAndReturnError:(NSError **)outError NS_AVAILABLE(10_6, NA);
79
80/*!
81 @method unreachableSubnodeNamesAndReturnError:
82 @abstract Will return NSArray of names of subnodes that are not currently reachable.
83 @discussion Will return NSArray of names of subnodes that are not currently reachable. Commonly used with Search policy
84 nodes to determine if any nodes are currently unreachable, but may also return other subnodes if the
85 OpenDirectory plugin supports. outError is optional parameter, nil can be passed if error details are not needed.
86*/
87- (NSArray *)unreachableSubnodeNamesAndReturnError:(NSError **)outError NS_AVAILABLE(10_6, NA);
88
89/*!
90 @property nodeName
91 @abstract The node name.
92 @discussion The node name, corresponding to its path in OpenDirectory.
93*/
94@property (nonatomic, readonly, copy) NSString *nodeName NS_AVAILABLE(10_6, NA);
95
96/*!
97 @method nodeDetails:error:
98 @abstract Returns a dictionary of information about the instance of ODNode
99 @discussion Returns a dictionary of information about the instance of ODNode. Details such as Trust information
100 (kODAttributeTypeTrustInformation) or other Node details can be retrieved. outError is optional parameter,
101 nil can be passed if error details are not needed.
102
103*/
104- (NSDictionary *)nodeDetailsForKeys:(NSArray *)inKeys error:(NSError **)outError NS_AVAILABLE(10_6, NA);
105
106/*!
107 @method supportedRecordTypesAndReturnError:
108 @abstract Returns a NSArray of the record types supported by this node.
109 @discussion Returns a NSArray of the record types supported by this node. If node does not support the check
110 then all possible types will be returned. outError is optional parameter, nil can be passed if error details
111 are not needed.
112*/
113- (NSArray *)supportedRecordTypesAndReturnError:(NSError **)outError NS_AVAILABLE(10_6, NA);
114
115/*!
116 @method supportedAttributesForRecordType:error:
117 @abstract Will return a list of attribute types supported for that attribute if possible
118 @discussion Will return a list of attribute types supported for that attribute if possible. If no specific
119 types are available, then all possible values will be returned instead. outError is optional parameter,
120 nil can be passed if error details are not needed.
121*/
122- (NSArray *)supportedAttributesForRecordType:(ODRecordType)inRecordType error:(NSError **)outError NS_AVAILABLE(10_6, NA);
123
124/*!
125 @method setCredentialsWithRecordType:recordName:password:error:
126 @abstract Sets the credentials for interaction with the ODNode
127 @discussion Sets the credentials for interaction with the ODNode. Record references, etc. will use these credentials
128 to query or change data. Setting the credentials on a node referenced by other OD object types will
129 change the credentials for all for all references. outError is optional parameter, nil can be passed if error
130 details are not needed.
131*/
132- (BOOL)setCredentialsWithRecordType:(ODRecordType)inRecordType recordName:(NSString *)inRecordName password:(NSString *)inPassword
133 error:(NSError **)outError NS_AVAILABLE(10_6, NA);
134
135/*!
136 @method setCredentialsWithRecordType:authType:authItems:outAuthItems:context:error:
137 @abstract Allows use of other OpenDirectory types of authentications to set the credentials for an ODNode
138 @discussion Allows the caller to use other types of authentications that are available in OpenDirectory, that may
139 require response-request loops, etc. Not all OD plugins will support this call, look for
140 kODErrorCredentialsMethodNotSupported in outError. outError is optional parameter, nil can be passed if
141 error details is not needed.
142*/
143- (BOOL)setCredentialsWithRecordType:(ODRecordType)inRecordType authenticationType:(ODAuthenticationType)inType
144 authenticationItems:(NSArray *)inItems continueItems:(NSArray **)outItems
145 context:(id *)outContext error:(NSError **)outError NS_AVAILABLE(10_6, NA);
146
147/*!
148 @method setCredentialsUsingKerberosCache:error:
149 @abstract Unsupported method.
150 @discussion Unsupported method.
151*/
152- (BOOL)setCredentialsUsingKerberosCache:(NSString *)inCacheName error:(NSError **)outError NS_DEPRECATED_MAC(10_6, 10_7) NS_AVAILABLE(10_6, NA);
153
154/*!
155 @method createRecordWithRecordType:name:attributes:error:
156 @abstract Creates a record in this node, using the given name and attributes.
157 @discussion Takes all the provided attributes and type to create an entire record. The function will assign a
158 UUID to the record automatically. This UUID can be overwritten by the client by passing with the
159 other attributes. inAttributes is optional, nil can be passed if no other attributes are to be set.
160*/
161- (ODRecord *)createRecordWithRecordType:(ODRecordType)inRecordType name:(NSString *)inRecordName
162 attributes:(NSDictionary *)inAttributes error:(NSError **)outError NS_AVAILABLE(10_6, NA);
163
164/*!
165 @method recordWithRecordType:name:attributes:error:
166 @abstract Returns an ODRecord object that references the requested type and name
167 @discussion Returns an ODRecord object that references the requested type and name. The record will have cached the
168 attributes requested. Further attributes can be requested via ODRecord APIs. For performance it is best
169 to ask for as many attributes that are needed as possible up front.
170*/
171- (ODRecord *)recordWithRecordType:(ODRecordType)inRecordType name:(NSString *)inRecordName attributes:(id)inAttributes
172 error:(NSError **)outError NS_AVAILABLE(10_6, NA);
173
174/*!
175 @method customCall:sendData:error:
176 @abstract Sends a custom code to the node; input and output data formats are specific to the call.
177 @discussion Sends a custom code to the node; input and output data formats are specific to the call. outError is
178 optional parameter, nil can be passed if error details are not needed.
179*/
180- (NSData *)customCall:(NSInteger)inCustomCode sendData:(NSData *)inSendData error:(NSError **)outError NS_AVAILABLE(10_6, NA);
181
182/*!
183 @method customFunction:payload:error:
184 @abstract Sends a custom function call to the node; data is a type specific to the call.
185 @discussion Sends a custom function call to the node; data is a type specific to the call. 'error' is an
186 optional parameter therefore nil can be passed if error details are not needed. Return type is
187 defined by the custom function requested.
188*/
189- (id)customFunction:(NSString *)function payload:(id)payload error:(NSError **)error NS_AVAILABLE(10_9, NA);
190
191/*!
192 * @method configuration
193 *
194 * @abstract
195 * Returns an ODConfiguration object for the node.
196 *
197 * @discussion
198 * Returns an ODConfiguration object for the node.
199 */
200@property (readonly, strong) ODConfiguration *configuration;
201
202/*!
203 @method policiesAndReturnError:
204 @abstract This will copy any policies configured for the node.
205 @discussion This will copy any policies configured for the node.
206*/
207- (NSDictionary *)policiesAndReturnError:(NSError **)error __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_10, __IPHONE_NA, __IPHONE_NA, "use accountPoliciesAndReturnError:");
208
209/*!
210 @function supportedPoliciesAndReturnError:
211 @abstract This will return a dictionary of supported policies.
212 @discussion This will return a dictionary of supported policies, if appropriate, the value will be the maximum value allowed
213 for the policy in question. For example, if password history is available, it will state how much history is
214 supported.
215*/
216- (NSDictionary *)supportedPoliciesAndReturnError:(NSError **)error __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_9, __MAC_10_10, __IPHONE_NA, __IPHONE_NA);
217
218/*!
219 @function setPolicies:error:
220 @abstract This will set the policy for the node.
221 @discussion This will set the policy for the node. Policies are evaluated in combination with record-level policies.
222*/
223- (BOOL)setPolicies:(NSDictionary *)policies error:(NSError **)error __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_10, __IPHONE_NA, __IPHONE_NA, "use setAccountPolicies:error:");
224
225/*!
226 @function setPolicy:value:error:
227 @abstract This will set a specific policy setting for the node.
228 @discussion This will set a specific policy setting for the node.
229*/
230- (BOOL)setPolicy:(ODPolicyType)policy value:(id)value error:(NSError **)error __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_10, __IPHONE_NA, __IPHONE_NA, "use addAccountPolicy:toCategory:error:");
231
232/*!
233 @function removePolicy:value:error:
234 @abstract This will remove a specific policy setting from the node.
235 @discussion This will remove a specific policy setting from the node.
236*/
237- (BOOL)removePolicy:(ODPolicyType)policy error:(NSError **)error __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_10, __IPHONE_NA, __IPHONE_NA, "use removeAccountPolicy:fromCategory:error:");
238
239/*!
240 @method addAccountPolicy:toCategory:error:
241 @abstract This will add an account policy to the node for the specified category.
242 @discussion This will add an account policy to the node for the specified category.
243 The specified policy will be applied to all users in the
244 specified node when policies are evaluated.
245 @param policy a dictionary containing the specific policy to be added.
246 The dictionary may contain the following keys:
247 kODPolicyKeyIdentifier a required key identifying the policy.
248 kODPolicyKeyParameters an optional key containing a dictionary of
249 parameters that can be used for informational purposes or in
250 the policy format string.
251 kODPolicyKeyContent a required key specifying the policy,
252 from which a predicate will be created for evaluating
253 the policy.
254 @param category a valid ODPolicyCategoryType to which the specified policy will be added.
255 @param error an optional NSError reference for error details.
256 @result a BOOL which signifies if the policy addition succeeded, otherwise error is set.
257*/
258- (BOOL)addAccountPolicy:(NSDictionary *)policy toCategory:(ODPolicyCategoryType)category error:(NSError **)error __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);
259
260/*!
261 @method removeAccountPolicy:fromCategory:error:
262 @abstract This will remove an account policy from the node for the specified category.
263 @discussion This will remove an account policy from the node for the specified category.
264 @param policy a dictionary containing the specific policy to be
265 removed, with the same format as described in addAccountPolicy.
266 @param category a valid ODPolicyCategoryType from which the specified policy will be removed.
267 @param error an optional NSError reference for error details.
268 @result a BOOL which signifies if the policy removal succeeded, otherwise error is set.
269*/
270- (BOOL)removeAccountPolicy:(NSDictionary *)policy fromCategory:(ODPolicyCategoryType)category error:(NSError **)error __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);
271
272/*!
273 @method setAccountPolicies:error:
274 @abstract This will set the policies for the node.
275 @discussion This will set the policies for the node, replacing any existing
276 policies. All of the policies in the set will be applied to all
277 users in the specified node when policies are evaluated.
278 @param policies a dictionary containing all of the policies to be set
279 for the node. The dictionary may contain the following keys:
280 kODPolicyCategoryAuthentication an optional key with a value
281 of an array of policy dictionaries that specify when
282 authentications should be allowed.
283 kODPolicyCategoryPasswordContent an optional key with a
284 value of an array of policy dictionaries the specify the
285 required content of passwords.
286 kODPolicyCategoryPasswordChange an optional key with a value
287 of an array of policy dictionaries that specify when
288 passwords are required to be changed.
289 @param error an optional NSError reference for error details.
290 @result a BOOL which signifies if the policy set succeeded, otherwise error is set.
291*/
292- (BOOL)setAccountPolicies:(NSDictionary *)policies error:(NSError **)error __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);
293
294/*!
295 @method accountPoliciesAndReturnError:
296 @abstract Returns a dictionary containing any policies configured for the node.
297 @discussion Returns a dictionary containing any policies configured for the node.
298 @param error an optional NSError reference for error details.
299 @result an NSDictionary containing all currently set policies. The
300 format of the dictionary is the same as described in
301 setAccountPolicies.
302*/
303- (NSDictionary *)accountPoliciesAndReturnError:(NSError **)error __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);
304
305/*!
306 @method passwordContentCheck:forRecordName:error:
307 @abstract Validates a password against the node's password content policies.
308 @discussion Validates a password against the node's password content policies.
309 The node's password content policies will be evaluated to
310 determine if the password is acceptable. May be used prior to
311 creating the record.
312
313 This check is only definitive at the time it was requested. The
314 policy or the environment could change before the password change
315 is actually requested. Errors from the password change request
316 should be consulted.
317
318 @param password the password to be evaluated against the content policies.
319 @param recordName the name of the record.
320 @param error an optional NSError reference for error details.
321 @result a bool which signifies if the password passes all content policies, otherwise error is set.
322 */
323- (BOOL)passwordContentCheck:(NSString *)password forRecordName:(NSString *)recordName error:(NSError **)error __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);
324@end