Ticket #384: SCDynamicStoreCopySpecific.h

/*
 * Copyright (c) 2000-2005 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

#ifndef _SCDYNAMICSTORECOPYSPECIFIC_H
#define _SCDYNAMICSTORECOPYSPECIFIC_H

#include <sys/cdefs.h>
#include <sys/types.h>
#include <CoreFoundation/CoreFoundation.h>
#include <SystemConfiguration/SCDynamicStore.h>


/*!
        @header SCDynamicStoreCopySpecific
        @discussion The functions of the SCDynamicStoreCopySpecific API
                allow an application to determine specific configuration
                information about the current system (for example, the
                computer or sharing name, the currently logged-in user, etc.).
 */


__BEGIN_DECLS

/*!
        @function SCDynamicStoreCopyComputerName
        @discussion Gets the current computer name.
        @param store An SCDynamicStoreRef representing the dynamic store
                session that should be used for communication with the server.
                If NULL, a temporary session will be used.
        @param nameEncoding A pointer to memory that, if non-NULL, will be
                filled with the encoding associated with the computer or
                host name.
        @result Returns the current computer name;
                NULL if the name has not been set or if an error was encountered.
                You must release the returned value.
 */
CFStringRef
SCDynamicStoreCopyComputerName          (
                                        SCDynamicStoreRef       store,
                                        CFStringEncoding        *nameEncoding
                                        );

/*!
        @function SCDynamicStoreCopyConsoleUser
        @discussion Gets the name, user ID, and group ID of the currently
                logged-in user.

                Note: this function only provides information about the
                      primary console.  It does not provide any details
                      about console sessions that have fast user switched
                      out or about other consoles.
        @param store An SCDynamicStoreRef representing the dynamic store
                session that should be used for communication with the server.
                If NULL, a temporary session will be used.
        @param uid A pointer to memory that will be filled with the user ID
                of the current console user. If NULL, this value will not
                be returned.
        @param gid A pointer to memory that will be filled with the group ID
                of the current console user. If NULL, this value will not be
                returned.
        @result Returns the user currently logged into the system;
                NULL if no user is logged in or if an error was encountered.
                You must release the returned value.
 */
CFStringRef
SCDynamicStoreCopyConsoleUser           (
                                        SCDynamicStoreRef       store,
                                        uid_t                   *uid,
                                        gid_t                   *gid
                                        );

/*!
        @function SCDynamicStoreCopyLocalHostName
        @discussion Gets the current local host name.
        @param store An SCDynamicStoreRef representing the dynamic store
                session that should be used for communication with the server.
                If NULL, a temporary session will be used.
        @result Returns the current local host name;
                NULL if the name has not been set or if an error was encountered.
                You must release the returned value.
 */
CFStringRef
SCDynamicStoreCopyLocalHostName         (
                                        SCDynamicStoreRef       store
                                        );

/*!
        @function SCDynamicStoreCopyLocation
        @discussion Gets the current location identifier.
        @param store An SCDynamicStoreRef representing the dynamic store
                session that should be used for communication with the server.
                If NULL, a temporary session will be used.
        @result Returns a string representing the current location identifier;
                NULL if no location identifier has been defined or if an error
                was encountered.
                You must release the returned value.
 */
CFStringRef
SCDynamicStoreCopyLocation              (
                                        SCDynamicStoreRef       store
                                        );

/*!
        @function SCDynamicStoreCopyProxies
        @discussion Gets the current internet proxy settings.
                The returned proxy settings dictionary includes:

                <TABLE BORDER>
                <TR>
                        <TH>key</TD>
                        <TH>type</TD>
                        <TH>description</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesExceptionsList</TD>
                        <TD>CFArray[CFString]</TD>
                        <TD>Host name patterns which should bypass the proxy</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesHTTPEnable</TD>
                        <TD>CFNumber (0 or 1)</TD>
                        <TD>Enables/disables the use of an HTTP proxy</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesHTTPProxy</TD>
                        <TD>CFString</TD>
                        <TD>The proxy host</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesHTTPPort</TD>
                        <TD>CFNumber</TD>
                        <TD>The proxy port number</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesHTTPSEnable</TD>
                        <TD>CFNumber (0 or 1)</TD>
                        <TD>Enables/disables the use of an HTTPS proxy</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesHTTPSProxy</TD>
                        <TD>CFString</TD>
                        <TD>The proxy host</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesHTTPSPort</TD>
                        <TD>CFNumber</TD>
                        <TD>The proxy port number</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesFTPEnable</TD>
                        <TD>CFNumber (0 or 1)</TD>
                        <TD>Enables/disables the use of an FTP proxy</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesFTPProxy</TD>
                        <TD>CFString</TD>
                        <TD>The proxy host</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesFTPPort</TD>
                        <TD>CFNumber</TD>
                        <TD>The proxy port number</TD>
                </TR>
                <TR>
                        <TD>kSCPropNetProxiesFTPPassive</TD>
                        <TD>CFNumber (0 or 1)</TD>
                        <TD>Enable passive mode operation for use behind connection
                        filter-ing firewalls.</TD>
                </TR>
                </TABLE>

                Other key-value pairs are defined in the SCSchemaDefinitions.h
                header file.
        @param store An SCDynamicStoreRef representing the dynamic store
                session that should be used for communication with the server.
                If NULL, a temporary session will be used.
        @result Returns a dictionary containing key-value pairs that represent
                the current internet proxy settings;
                NULL if no proxy settings have been defined or if an error
                was encountered.
                You must release the returned value.
 */
CFDictionaryRef
SCDynamicStoreCopyProxies               (
                                        SCDynamicStoreRef       store
                                        );

__END_DECLS

#endif /* _SCDYNAMICSTORECOPYSPECIFIC_H */