1/*
2 * Copyright (c) 2000-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#ifndef __WEBDAVLIB_H__
25#define __WEBDAVLIB_H__
26
27#include <CoreFoundation/CoreFoundation.h>
28
29enum WEBDAVLIBAuthStatus
30{
31	WEBDAVLIB_Success = 0,
32	WEBDAVLIB_ProxyAuth = 1,
33	WEBDAVLIB_ServerAuth = 2,
34	WEBDAVLIB_UnexpectedStatus = 3,
35	WEBDAVLIB_IOError = 4
36};
37
38//
39// enum WEBDAVLIBAuthStatus queryForProxy(CFURLRef a_url, CFDictionaryRef proxyInfo, int *error)
40//
41// Sends and OPTIONS request to the server and determines if an http/https authenticating
42// porxy server exists.  SSL connections are supported.
43//
44// Return Values:
45//
46// WEBDAVLIB_Success    - An OPTIONS reply was received without requiring credentials.
47//						  The output arg 'error' is set to zero.
48//
49// WEBDAVLIB_ServerAuth - The server is requesting credentials (http status 401),
50//                        no proxy server was encountered.
51//						  The output arg 'error' is set to EAUTH.
52//
53// WEBDAVLIB_ProxyAuth  - An authenticating proxy server was found (http status 407).
54//						  The output arg 'error' is set to EAUTH.
55//
56//                        The following keys are returned in the 'proxyInfo' dictionary:
57//                        kWebDAVLibProxyServerNameKey
58//                        kWebDAVLibProxyRealmKey
59//                        kWebDAVLibProxyPortKey
60//                        kWebDAVLibProxySchemeKey
61//
62// WEBDAVLIB_UnexpectedStatus  Received an unexpected http status (i.e. not 200, 401, or 407).
63//							   The output arg 'error' is set to EIO.
64//
65// WEBDAVLIB_IOError	- This is a catch-all for anything else that went wrong.
66//						  The output arg 'error' provides more detail.
67//
68
69// Keys defining a proxy server
70#define kWebDAVLibProxyServerNameKey	CFSTR("ProxyServer")
71#define kWebDAVLibProxyRealmKey			CFSTR("ProxyRealm")
72#define kWebDAVLibProxyPortKey			CFSTR("ProxyPort")
73#define kWebDAVLibProxySchemeKey		CFSTR("ProxyScheme")	// http or https
74
75extern enum WEBDAVLIBAuthStatus queryForProxy(CFURLRef a_url, CFMutableDictionaryRef proxyInfo, int *error);
76
77
78//
79// enum WEBDAVLIBAuthStatus connectToServer(CFURLRef a_url, CFDictionaryRef creds, boolean_t requireSecureLogin, int *error)
80//
81// Test if a connection can be established with a server by sending an OPTIONS request,
82// performing authentication when required.  SSL connections are supported.  This provides
83// a simple way of testing credentials.
84//
85// A CFDictionary containing credentials (both server and proxy server) can be passed
86// in the 'creds' input argument. The input keys are:
87//
88//			kWebDAVLibUserNameKey		(CFString)
89//			kWebDAVLibPasswordKey		(CFString)
90//			kWebDAVLibProxyUserNameKey	(CFString)
91//			kWebDAVLibProxyPasswordKey	(CFString)
92//
93// If 'requireSecureLogin' is TRUE, then the connection will fail (EAUTH) if credentials cannot be
94// sent securely (fails for Basic Authentication without an SSL connection).  In this case the
95// return value is  WEBDAVLIB_ServerAuth or  WEBDAVLIB_ProxyAuth and 'error' is set to EAUTH.
96//
97// Return Values:
98//
99// WEBDAVLIB_Success    - Success. The connection attempt was successful.
100//						  The output arg 'error' is set to zero.
101//
102// WEBDAVLIB_ServerAuth - The server requires authentication (http status 401). If server
103//						  credentials were passed, then they were not accepted by the server.
104//						  The output arg 'error' is set to EAUTH.
105//
106// WEBDAVLIB_ProxyAuth  - The proxy server requires authentication (http status 407). If proxy server
107//						  credentials were passed, then they were not accepted by the proxy server.
108//
109// WEBDAVLIB_UnexpectedStatus  Received an unexpected http status (i.e. not 200, 401, or 407).
110//							   The output arg 'error' is set to EIO.
111//
112// WEBDAVLIB_IOError	- This is a catch-all for anything else that went wrong.
113//						  The output arg 'error' provides more detail.
114//
115
116// Keys for passing server and proxy server credentials
117#define kWebDAVLibUserNameKey	CFSTR("UserName")
118#define kWebDAVLibPasswordKey	CFSTR("Password")
119#define kWebDAVLibProxyUserNameKey	CFSTR("ProxyUserName")
120#define kWebDAVLibProxyPasswordKey	CFSTR("ProxyPassword")
121
122extern enum WEBDAVLIBAuthStatus connectToServer(CFURLRef a_url, CFDictionaryRef creds, boolean_t requireSecureLogin, int *error);
123
124#endif
125