ADC Home > Reference Library > Reference > Graphics & Imaging > Image Capture Applications Reference

ICAApplication.h

Includes:

Overview

ICAApplication.h defines structures and functions that are used by applications programs to access image-capture devices such as cameras, scanners, and phones

Functions

ICACloseSession: Use this API to close a session on a camera device. For a scanner device use the ICAScannerCloseSession API.
ICACopyObjectData: Use this API to get a copy of data associated with a file object.
ICACopyObjectPropertyDictionary: Use this API to get a CFDictionaryRef containing all the properties for an object specified in the object field of the ICACopyObjectPropertyDictionaryPB struct.
ICACopyObjectThumbnail: Use this API to get a thumbnail associated with an object.
ICADownloadFile: Use this API to download a file to disk.
ICAGetChildCount: Fetches the number of children of an object. This API is deprecated in 10.5.
ICAGetDeviceList: Fetches the object at the top of the object heirarchy.
ICAGetNthChild: Fetches the child of a given object at a given index. This API is deprecated in 10.5.
ICAGetNthProperty: Use this API to get an object's specific property and its information. This API is deprecated in 10.5.
ICAGetObjectInfo: Use this API to get information about an object. This API is deprecated in 10.5.
ICAGetObjectRefCon: Use this API to get an arbitrary refcon associated with an object. This API is deprecated in 10.5.
ICAGetParentOfObject: Use this API to get an object's parent object and its information. This API is deprecated in 10.5.
ICAGetParentOfProperty: Uset this API to get a property's parent object and its information. This API is deprecated in 10.5.
ICAGetPropertyByType: Use this API to get an object's property by type and its information. This API is deprecated in 10.5.
ICAGetPropertyCount: Use this API to get the number of properties an object has. This API is deprecated in 10.5.
ICAGetPropertyData: Use this API to get data associated with a property. This API is deprecated in 10.5. Use one of the ICACopy* APIs instead.
ICAGetPropertyInfo: Use this API to get information about a property. This API is deprecated in 10.5.
ICAGetPropertyRefCon: Use this API to get an arbitrary refcon associated with a property. This API is deprecated in 10.5.
ICAGetRootOfObject: Use this API to get an object's root object (in the object hierarchy) and its information. This API is deprecated in 10.5.
ICAGetRootOfProperty: Uset this API to get a property's root object (in the object hierarchy) and its information. This API is deprecated in 10.5.
ICAImportImage: This API displays a Common User Interface panel similar to the user interface of Image Capture Application. This allows the user to work a camera or a scanner.
ICALoadDeviceModule: Use this API to load a device module.
ICAObjectSendMessage: Use this API to send a message to a device object.
ICAOpenSession: Use this API to open a session on a camera device. For a scanner device use the ICAScannerOpenSession API.
ICARegisterEventNotification: This API is deprecated in 10.5. Use ICARegisterForEventNotification API instead.
ICARegisterForEventNotification: Use this API to register with Image Capture framework to receive notification about events of interest.
ICAScannerCloseSession: Use this API to close a session on a scanner device. For a camera device use the ICACloseSession API.
ICAScannerGetParameters: Use this API to get information about the scanner such as resolution, scanning area, etc.
ICAScannerInitialize: Use this API to initialize a scanner device.
ICAScannerOpenSession: Use this API to open a session on a scanner device. For a camera device use the ICAOpenSession API.
ICAScannerSetParameters: Use this API to specify scan parameters that will be used when a scan is initiated via an ICAScannerStart.
ICAScannerStart: Use this API start a scan based on the parameters that were specified in a previous ICAScannerSetParameters call.
ICAScannerStatus: Use this API to get information about the current status of the scanner.
ICASetObjectRefCon: Use this API to set an arbitrary refcon for an object. This API is deprecated in 10.5.
ICASetPropertyData: Use this API to set data for a property. This API is deprecated in 10.5.
ICASetPropertyRefCon: Use this API to set an arbitrary refcon for a property. This API is deprecated in 10.5.
ICAShowDeviceBrowser: Use this API to display a device browser user interface from any Image Capture client application.
ICAUnloadDeviceModule: Uset this API to unload a device module.
ICAUploadFile: Use this API to upload a file to a device that supports this capability.

ICACloseSession

Use this API to close a session on a camera device. For a scanner device use the ICAScannerCloseSession API.

extern ICAError ICACloseSession( 
    ICACloseSessionPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICACloseSessionPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICACloseSession function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

This API closes an open session on a camera device. If the camera does not have any open sessions, the device module controlling the camera is free to give it up during fast-user-switching.

Availability: Introduced in Mac OS X v10.4.

ICACopyObjectData

Use this API to get a copy of data associated with a file object.

extern ICAError ICACopyObjectData( 
    ICACopyObjectDataPB *params, 
    ICACompletion completionProc );

Parameters

params: A pointer to ICACopyObjectDataPB struct <--
completionProc: A pointer to a completion routine that will be invoked at the completion of this function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get a copy of data associated with a file object. This API should be used in place of ICAGetPropertyData.

Availability: Introduced in Mac OS X v10.5.

ICACopyObjectPropertyDictionary

Use this API to get a CFDictionaryRef containing all the properties for an object specified in the object field of the ICACopyObjectPropertyDictionaryPB struct.

extern ICAError ICACopyObjectPropertyDictionary( 
    ICACopyObjectPropertyDictionaryPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICACopyObjectPropertyDictionaryPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICACopyObjectPropertyDictionary function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

This API is the preferred way to get to any ICAObject related property data.



        Example:
        
        void  CopyObjectPropertyDictionary()
        {
            OSErr                             err;
            ICACopyObjectPropertyDictionaryPB pb = {};

            pb.object = <#ICAObject object#>;
            err = ICACopyObjectPropertyDictionary( &pb, NULL );

            if ( noErr != err)
            {
                // handle error
            }
            else
            {
                // Make sure to release the returned dictionary
                // pb.theDict   // CFDictionaryRef *
            }
        }

Availability: Introduced in Mac OS X v10.1.

ICACopyObjectThumbnail

Use this API to get a thumbnail associated with an object.

extern ICAError ICACopyObjectThumbnail( 
    ICACopyObjectThumbnailPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICACopyObjectThumbnailPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICACopyObjectThumbnail function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

This is the recommended way to get the thumbnail of an object. Getting the thumbnail using ICAGetPropertyData is deprecaed in 10.5.



        Example:
        
        void CopyObjectThumbnail()
        {
            OSErr                     err;
            ICACopyObjectThumbnailPB  pb = {};

            pb.object          = <#ICAObject object#>;
            pb.thumbnailFormat = <#OSType thumbnailFormat#>;
            
            err = ICACopyObjectThumbnail( &pb, NULL );

            if ( noErr != err )
            {
                // handle error
            }
            else
            {
                // Make sure to release the thumbnailData
                // pb.thumbnailData   // CFDataRef *
            }
        }

Availability: Introduced in Mac OS X v10.3.

ICADownloadFile

Use this API to download a file to disk.

extern ICAError ICADownloadFile( 
    ICADownloadFilePB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICADownloadFilePB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICADownloadFile function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

This API is a convenient way to download a file to disk. To receive the image data in memory use ICACopyObjectData. Using ICAGetPropertyData is not recommend for this purpose since ICAGetPropertyData is Deprecated in 10.5.



        Example:
        
        void DownloadFile()
        {
            OSErr             err;
            ICADownloadFilePB pb = {};

            pb.flags         = <#UInt32 flags#>;
            pb.rotationAngle = <#Fixed rotationAngle#>;
            pb.object        = <#ICAObject object#>;
            pb.fileCreator   = <#OSType fileCreator#>;
            pb.dirFSRef      = <#FSRef * dirFSRef#>;
            pb.fileType      = <#OSType fileType#>;
            
            err = ICADownloadFile( &pb, NULL );

            if ( noErr != err )
            {
                // handle error
            }
            else
            {
                // pb.fileFSRef   // FSRef *
            }
        }

Availability: Introduced in Mac OS X v10.1.

ICAGetChildCount

Fetches the number of children of an object. This API is deprecated in 10.5.

extern ICAError ICAGetChildCount( 
    ICAGetChildCountPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetChildCountPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetChildCount function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Image Capture framework presents cameras and scanners, their contents and their capabilities as a heirarchy of objects and their properties. The ICAGetChildCount function fetches the number of children of the object specified in the object field of paramter pb.



        Example:
        
        UInt32 GetNumberOfDevices ()
        {
            ICAGetChildCountPB getChildCountPB;
            OSErr              err;
            
            memset(&getChildCountPB, 0, sizeof(ICAGetChildCountPB));
            getChildCountPB.object = GetDeviceList();
            err = ICAGetChildCount(&getChildCountPB, nil);
            
            return getChildCountPB.count;
        }

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetDeviceList

Fetches the object at the top of the object heirarchy.

extern ICAError ICAGetDeviceList( 
    ICAGetDeviceListPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetDeviceListPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetDeviceList function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Image Capture framework presents cameras and scanners, their contents and their capabilities as a heirarchy of objects and their properties. The device list object is at the top of the heirarchy of objects. The ICAGetDeviceList function fetches this object in the object field of parameter pb. Children of the device list object can be accessed by passing the device list object to functions ICAGetChildCount() and ICAGetNthChild().



        Example:
        
        ICAObject GetDeviceList()
        {
            ICAGetDeviceListPB getDeviceListPB  = {};
            ICAObject          deviceList       = 0;
            OSErr              err;
            
            err = ICAGetDeviceList( &getDeviceListPB, nil );
            
            if ( noErr == err )
            {
                deviceList = getDeviceListPB.object;
            }
            
            return deviceList;
        }

Availability: Introduced in Mac OS X v10.0.

ICAGetNthChild

Fetches the child of a given object at a given index. This API is deprecated in 10.5.

extern ICAError ICAGetNthChild( 
    ICAGetNthChildPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetNthChildPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetNthChild function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Image Capture framework presents cameras and scanners, their contents and their capabilities as a heirarchy of objects and their properties. The ICAGetNthChild function fetches the child object of an object specifed in the parentObject field of the parameter pb at the index specified in the index field of the parameter pb. The index is zero-based. The function also returns the ICAObjectInfo for the child object in the childInfo field of the parameter pb.



        Example:
        
        ICAObject GetFirstDevice () {
            ICAGetNthChildPB getNthChildPB;
            ICAObject        firstDevice = NULL;
            OSErr            err;
            UInt32           count;
            
            count = GetNumberOfDevices();
            if (count > 0)
            {
                memset(&getNthChildPB, 0, sizeof(ICAGetNthChildPB));
                getNthChildPB.parentObject = Get_Device_List();
                getNthChildPB.index = 0;
                err = ICAGetNthChild (&getNthChildPB, nil);
                if (noErr == err)
                {
                    firstDevice = getNthChildPB.childObject;
                }
            }
            return firstDevice;
        }

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetNthProperty

Use this API to get an object's specific property and its information. This API is deprecated in 10.5.

extern ICAError ICAGetNthProperty( 
    ICAGetNthPropertyPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetNthPropertyPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetNthProperty function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get an object's specific property and its information. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetObjectInfo

Use this API to get information about an object. This API is deprecated in 10.5.

extern ICAError ICAGetObjectInfo( 
    ICAGetObjectInfoPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetObjectInfoPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetObjectInfo function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get information about an object. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetObjectRefCon

Use this API to get an arbitrary refcon associated with an object. This API is deprecated in 10.5.

extern ICAError ICAGetObjectRefCon( 
    ICAGetObjectRefConPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetObjectRefConPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetObjectRefCon function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get an arbitrary refcon associated with an object. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetParentOfObject

Use this API to get an object's parent object and its information. This API is deprecated in 10.5.

extern ICAError ICAGetParentOfObject( 
    ICAGetParentOfObjectPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetParentOfObjectPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetParentOfObject function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get an object's parent object and its information. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetParentOfProperty

Uset this API to get a property's parent object and its information. This API is deprecated in 10.5.

extern ICAError ICAGetParentOfProperty( 
    ICAGetParentOfPropertyPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetParentOfPropertyPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetParentOfProperty function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Uset this API to get a property's parent object and its information. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetPropertyByType

Use this API to get an object's property by type and its information. This API is deprecated in 10.5.

extern ICAError ICAGetPropertyByType( 
    ICAGetPropertyByTypePB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetPropertyByTypePB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetPropertyByType function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get an object's property by type and its information. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetPropertyCount

Use this API to get the number of properties an object has. This API is deprecated in 10.5.

extern ICAError ICAGetPropertyCount( 
    ICAGetPropertyCountPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetPropertyCountPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetPropertyCount function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get the number of properties an object has. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetPropertyData

Use this API to get data associated with a property. This API is deprecated in 10.5. Use one of the ICACopy* APIs instead.

extern ICAError ICAGetPropertyData( 
    ICAGetPropertyDataPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetPropertyDataPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetPropertyData function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get data associated with a property. This API is deprecated in 10.5. Use one of the ICACopy* APIs instead.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetPropertyInfo

Use this API to get information about a property. This API is deprecated in 10.5.

extern ICAError ICAGetPropertyInfo( 
    ICAGetPropertyInfoPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetPropertyInfoPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetPropertyInfo function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get information about a property. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetPropertyRefCon

Use this API to get an arbitrary refcon associated with a property. This API is deprecated in 10.5.

extern ICAError ICAGetPropertyRefCon( 
    ICAGetPropertyRefConPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetPropertyRefConPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetPropertyRefCon function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get an arbitrary refcon associated with a property. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetRootOfObject

Use this API to get an object's root object (in the object hierarchy) and its information. This API is deprecated in 10.5.

extern ICAError ICAGetRootOfObject( 
    ICAGetRootOfObjectPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetRootOfObjectPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetRootOfObject function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get an object's root object (in the object hierarchy) and its information. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetRootOfProperty

Uset this API to get a property's root object (in the object hierarchy) and its information. This API is deprecated in 10.5.

extern ICAError ICAGetRootOfProperty( 
    ICAGetRootOfPropertyPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAGetRootOfPropertyPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAGetRootOfProperty function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Uset this API to get a property's root object (in the object hierarchy) and its information. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAImportImage

This API displays a Common User Interface panel similar to the user interface of Image Capture Application. This allows the user to work a camera or a scanner.

extern ICAError ICAImportImage( 
    ICAImportImagePB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAImportImagePB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAImportImage function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to add Image Capture support to an application.



        Example:
        
        void ImportImage()
        {
            OSErr             err;
            ICAImportImagePB  pb = {};

            pb.deviceObject       = 0;
            pb.flags              = 0;
            pb.supportedFileTypes = (CFArrayRef)[NSArray arrayWithObjects: @"tif", @"tiff", @"jpg", NULL];
            
            err = ICAImportImage(&pb, NULL);

            if ( noErr != err )
            {
                // handle error
            }
            else
            {
                // Process the importedImages array
                // pb.importedImages   // CFArrayRef *
            }
        }

Availability: Introduced in Mac OS X v10.3.

ICALoadDeviceModule

Use this API to load a device module.

extern ICAError ICALoadDeviceModule( 
    ICALoadDeviceModulePB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICALoadDeviceModulePB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICALoadDeviceModule function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Typically, connecting a FireWire or an USB device will automatically load an appropriate device module. This API is needed only for loading a device module manually for devices that do not use a hot-plug interface, such as Bluetooth, SCSI, or TCP/IP.

Availability: Introduced in Mac OS X v10.4.

ICAObjectSendMessage

Use this API to send a message to a device object.

extern ICAError ICAObjectSendMessage( 
    ICAObjectSendMessagePB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAObjectSendMessagePB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAObjectSendMessage function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to send a message to a device object. All devices do not respond to all the messages defined above.

Availability: Introduced in Mac OS X v10.0.

ICAOpenSession

Use this API to open a session on a camera device. For a scanner device use the ICAScannerOpenSession API.

extern ICAError ICAOpenSession( 
    ICAOpenSessionPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAOpenSessionPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAOpenSession function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

This API gets a session ID for a open session on a camera device. Since access to cameras is generally not be session-based, this API generall will not fail. If the camera has open session, the device module controlling the camera will continue to control it during fast-user-switching.

Availability: Introduced in Mac OS X v10.4.

ICARegisterEventNotification

This API is deprecated in 10.5. Use ICARegisterForEventNotification API instead.

extern ICAError ICARegisterEventNotification( 
    ICARegisterEventNotificationPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICARegisterEventNotificationPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICARegisterEventNotification function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

This API is deprecated in 10.5. Use ICARegisterForEventNotification API instead.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICARegisterForEventNotification

Use this API to register with Image Capture framework to receive notification about events of interest.

extern ICAError ICARegisterForEventNotification( 
    ICARegisterForEventNotificationPB *params, 
    ICACompletion completionProc );

Parameters

params: A pointer to ICARegisterForEventNotificationPB struct <--
completionProc: A pointer to a completion routine that will be invoked at the completion of this function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Availability: Introduced in Mac OS X v10.5.

ICAScannerCloseSession

Use this API to close a session on a scanner device. For a camera device use the ICACloseSession API.

extern ICAError ICAScannerCloseSession( 
    ICAScannerCloseSessionPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAScannerCloseSessionPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAScannerCloseSession function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

This API closes an open session, allowing other clients to work with the scanner.

Availability: Introduced in Mac OS X v10.2

ICAScannerGetParameters

Use this API to get information about the scanner such as resolution, scanning area, etc.

extern ICAError ICAScannerGetParameters( 
    ICAScannerGetParametersPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAScannerGetParametersPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAScannerGetParameters function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get information about the scanner such as resolution, scanning area, etc.

Availability: Introduced in Mac OS X v10.2

ICAScannerInitialize

Use this API to initialize a scanner device.

extern ICAError ICAScannerInitialize( 
    ICAScannerInitializePB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAScannerInitializePB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAScannerInitialize function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

After opening a session on a scanner device, use this API to set an initial state for the scanner.

Availability: Introduced in Mac OS X v10.2

ICAScannerOpenSession

Use this API to open a session on a scanner device. For a camera device use the ICAOpenSession API.

extern ICAError ICAScannerOpenSession( 
    ICAScannerOpenSessionPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAScannerOpenSessionPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAScannerOpenSession function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

For a given scanner, this API returns a unique session ID that allows you to work with the device. This API will fail, if a session is already open.

Availability: Introduced in Mac OS X v10.2

ICAScannerSetParameters

Use this API to specify scan parameters that will be used when a scan is initiated via an ICAScannerStart.

extern ICAError ICAScannerSetParameters( 
    ICAScannerSetParametersPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAScannerSetParametersPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAScannerSetParameters function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to specify scan parameters that will be used when a scan is initiated via an ICAScannerStart.

Availability: Introduced in Mac OS X v10.2

ICAScannerStart

Use this API start a scan based on the parameters that were specified in a previous ICAScannerSetParameters call.

extern ICAError ICAScannerStart( 
    ICAScannerStartPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAScannerStartPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAScannerStart function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API start a scan based on the parameters that were specified in a previous ICAScannerSetParameters call.

Availability: Introduced in Mac OS X v10.2

ICAScannerStatus

Use this API to get information about the current status of the scanner.

extern ICAError ICAScannerStatus( 
    ICAScannerStatusPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAScannerStatusPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAScannerStatus function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to get information about the current status of the scanner.

Availability: Introduced in Mac OS X v10.2

ICASetObjectRefCon

Use this API to set an arbitrary refcon for an object. This API is deprecated in 10.5.

extern ICAError ICASetObjectRefCon( 
    ICASetObjectRefConPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICASetObjectRefConPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICASetObjectRefCon function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to set an arbitrary refcon for an object. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICASetPropertyData

Use this API to set data for a property. This API is deprecated in 10.5.

extern ICAError ICASetPropertyData( 
    ICASetPropertyDataPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICASetPropertyDataPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICASetPropertyData function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to set data for a property. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICASetPropertyRefCon

Use this API to set an arbitrary refcon for a property. This API is deprecated in 10.5.

extern ICAError ICASetPropertyRefCon( 
    ICASetPropertyRefConPB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICASetPropertyRefConPB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICASetPropertyRefCon function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

Use this API to set an arbitrary refcon for a property. This API is deprecated in 10.5.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAShowDeviceBrowser

Use this API to display a device browser user interface from any Image Capture client application.

extern ICAError ICAShowDeviceBrowser( 
    CFDictionaryRef options );

Parameters

options: Set options to NULL to display the device browser with default settings. <-- This parameter is intended for future use.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

The device browser user interface allows the user to do the following: - enable and disable sharing of locally connected cameras and scanners. - connect to or disconnect from cameras and scanners shared by other computers. - configure WiFi capable cameras for use over the WiFi network.

Availability: Introduced in Mac OS X v10.5.

ICAUnloadDeviceModule

Uset this API to unload a device module.

extern ICAError ICAUnloadDeviceModule( 
    ICAUnloadDeviceModulePB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAUnloadDeviceModulePB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAUnloadDeviceModule function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

The device module providing this object will be unloaded, if this is the last device object provided by the device module.

Availability: Introduced in Mac OS X v10.4.

ICAUploadFile

Use this API to upload a file to a device that supports this capability.

extern ICAError ICAUploadFile( 
    ICAUploadFilePB *pb, 
    ICACompletion completion );

Parameters

pb: A pointer to an ICAUploadFilePB parameter block.
completion: A pointer to a completion routine that will be invoked at the completion of ICAUploadFile function. Set this parameter to NULL to invoke this API synchronously.

Return Value

Returns an error code defined in ICAApplication.h

Discussion

The device choses an appropriate destination location for the uploaded image and sends a kICANotificationTypeObjectAdded notification.



        Example:
        
        void  UploadFile()
        {
            OSErr           err;
            ICAUploadFilePB pb = {};

            pb.fileFSRef    = <#FSRef * fileFSRef#>;
            pb.flags        = <#UInt32 flags#>;
            pb.parentObject = <#ICAObject parentObject#>;
            
            err = ICAUploadFile( &pb, NULL );

            if ( noErr != err )
            {
                // handle error
            }
            else
            {
                // no return value(s)
            }
        }

Availability: Introduced in Mac OS X v10.4.

Typedefs

ICACloseSessionPB

typedef struct ICACloseSessionPB { 
    ICAHeader header; 
    ICASessionID sessionID; 
} ICACloseSessionPB;

Fields

header
See description for ICAHeader. <->

sessionID
A session ID of the session to be closed. <--

ICACopyObjectDataPB

typedef struct ICACopyObjectDataPB { 
    ICAHeader header; 
    ICAObject object; 
    size_t startByte; 
    size_t requestedSize; 
    CFDataRef *data; 
} ICACopyObjectDataPB;

Fields

header
See description for ICAHeader. <->

object
A file object. <--

startByte
Starting byte offset of the data in the file object. <--

requestedSize
Requested data size in bytes. <--

data
A pointer to CFDataRef in which the data will be returned. --> It is the responsibility fo the caller to release this object.

ICACopyObjectPropertyDictionaryPB

typedef struct ICACopyObjectPropertyDictionaryPB { 
    ICAHeader header; 
    ICAObject object; 
    CFDictionaryRef *theDict; 
} ICACopyObjectPropertyDictionaryPB;

Fields

header
See description for ICAHeader. <->

object
An object whose properties are being requested. <--

theDict
A dictionary to hold the properties. This must be released by the caller. -->

ICACopyObjectThumbnailPB

typedef struct ICACopyObjectThumbnailPB { 
    ICAHeader header; 
    ICAObject object; 
    OSType thumbnailFormat; 
    CFDataRef *thumbnailData; 
} ICACopyObjectThumbnailPB;

Fields

header
See description for ICAHeader. <->

object
An object whose thumbail is being requested. <--

thumbnailFormat
One of the format values defined above. <--

thumbnailData
A pointer to a CFDataRef holding the thumbnail data. The returned CFDataRef must be released by the caller. -->

ICADownloadFilePB

typedef struct ICADownloadFilePB { 
    ICAHeader header; 
    ICAObject object; 
    FSRef *dirFSRef; 
    UInt32 flags; 
    OSType fileType; 
    OSType fileCreator; 
    Fixed rotationAngle; 
    FSRef *fileFSRef; 
} ICADownloadFilePB;

Fields

header
See description for ICAHeader. <->

object
The file object. <--

dirFSRef
FSRef of destination directiory. <--

flags
Any combination of flag values defined above. <--

fileType
Four-char code indicating the type of file. <--

fileCreator
Four-char code indicating with the creator of the file. <--

rotationAngle
Rotation angle in steps of 90 degress. <--

fileFSRef
A pointer to FSRef struct to hold the FSRef of downloaded file. Set this to NULL if the FSRef of downloaded file is not of interest. -->

ICAExtendedRegisterEventNotificationPB

typedef struct ICAExtendedRegisterEventNotificationPB { 
    ICAHeader header; 
    ICAObject object; 
    OSType extd; 
    ICACompletion notifyProc; 
    UInt32 rawEventType; 
    OSType eventType; 
    OSType eventClass; 
    UInt32 eventDataSize; 
    ICAEventDataCookie eventDataCookie; 
    ICAObject deviceObject; 
} ICAExtendedRegisterEventNotificationPB;

Fields

header
See description for ICAHeader. <->

object
An object about which notifications are requested. <->

extd
Set this to kExtendedNotificationPB.

notifyProc
A callback function to receive the notifications. <--

rawEventType
Type of event that occurred. This could be vendor-specific.

eventType
Type of ImageCapture supported event that occurred. Refer to "Image Capture event types". <->

eventClass
Set to one of the following: 'kICAEventClassPTPStandard', 'kICAEventClassPTPStandard or any vendor-specific value. -->

eventDataSize
This is non-zero if there is additional data associated with this event. Additional event data can be fetched by calling ICAObjectSendMessage with messageType set to 'kICAMessageGetEventData', dataType set to value of eventDataCookie and dataSize set to value of eventDataSize. -->

eventDataCookie
A token identifying the additional data associated with this event. Additional event data can be fetched by calling ICAObjectSendMessage with messageType set to 'kICAMessageGetEventData', dataType set to value of eventDataCookie and dataSize set to value of eventDataSize. -->

deviceObject
Device object associated with the event. -->

Discussion

Use this parameter block with the 'extd' field set to kExtendedNotificationPB to receive detailed (extended) notifications. This parameter block is passed back with event notifications to the callback function.

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetChildCountPB

typedef struct ICAGetChildCountPB { 
    ICAHeader header; 
    ICAObject object; 
    UInt32 count; 
} ICAGetChildCountPB;

Fields

header
See description for ICAHeader. <-->

object
An object whose number of children is being requested by calling ICAGetChildCount. <--

count
Number of children returned by ICAGetChildCount, if successful. Should check err field in header before using the value returned in count. -->

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetDeviceListPB

typedef struct ICAGetDeviceListPB { 
    ICAHeader header; 
    ICAObject object; 
} ICAGetDeviceListPB;

Fields

header
See description for ICAHeader. <-->

object
The device list object, if ICAGetDeviceList returns successfully. -->

ICAGetNthChildPB

typedef struct ICAGetNthChildPB { 
    ICAHeader header; 
    ICAObject parentObject; 
    UInt32 index; 
    ICAObject childObject; 
    ICAObjectInfo childInfo; 
} ICAGetNthChildPB;

Fields

header
See description for ICAHeader. <-->

parentObject
An object whose child is being accessed. <--

index
A zero based index in to the children of 'parentObject'. <--

childObject
Child object, if ICAGetNthChild returns successfully. -->

childInfo
Object information for 'childObject', if ICAGetNthChild returns successfully. -->

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetNthPropertyPB

typedef struct ICAGetNthPropertyPB { 
    ICAHeader header; 
    ICAObject object; 
    UInt32 index; 
    ICAProperty property; 
    ICAPropertyInfo propertyInfo; 
} ICAGetNthPropertyPB;

Fields

header
See description for ICAHeader. <-->

object
An object whose property is being fetched. <--

index
A zero based index in to the properties of 'object'. <--

property
Property, if ICAGetNthProperty returns successfully. -->

propertyInfo
Property information for 'property', if ICAGetNthProperty returns successfully. -->

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetObjectInfoPB

typedef struct ICAGetObjectInfoPB { 
    ICAHeader header; 
    ICAObject object; 
    ICAObjectInfo objectInfo; 
} ICAGetObjectInfoPB;

Fields

header
See description for ICAHeader. <-->

object
An object whose information is being requested by calling ICAGetObjectInfo. <--

objectInfo
Object information for 'object', if ICAGetObjectInfo returns successfully. -->

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetObjectRefConPB

typedef struct ICAGetObjectRefConPB { 
    ICAHeader header; 
    ICAObject object; 
    unsigned long objectRefCon; 
} ICAGetObjectRefConPB;

Fields

header
See description for ICAHeader. <-->

object
An object whose associated refcon value is being accessed by calling ICAGetObjectRefCon. <--

objectRefCon
The refcon value. -->

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetParentOfObjectPB

typedef struct ICAGetParentOfObjectPB { 
    ICAHeader header; 
    ICAObject object; 
    ICAObject parentObject; 
    ICAObjectInfo parentInfo; 
} ICAGetParentOfObjectPB;

Fields

header
See description for ICAHeader. <-->

object
An object whose parent is being accessed by calling ICAGetParentOfObject. <--

parentObject
Parent object, if ICAGetParentOfObject returns successfully. -->

parentInfo
Object information for the parent object, if ICAGetParentOfObject returns successfully. -->

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetParentOfPropertyPB

typedef struct ICAGetParentOfPropertyPB { 
    ICAHeader header; 
    ICAProperty property; 
    ICAObject parentObject; 
    ICAObjectInfo parentInfo; 
} ICAGetParentOfPropertyPB;

Fields

header
See description for ICAHeader. <-->

property
A property whose parent is being fetched. <--

parentObject
Parent object, if ICAGetParentOfProperty returns successfully. -->

parentInfo
Information about 'parentObject', if ICAGetParentOfProperty returns successfully. -->

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetPropertyByTypePB

typedef struct ICAGetPropertyByTypePB { 
    ICAHeader header; 
    ICAObject object; 
    OSType propertyType; 
    ICAProperty property; 
    ICAPropertyInfo propertyInfo; 
} ICAGetPropertyByTypePB;

Fields

header
See description for ICAHeader. <-->

object
An object whose property is being fetched. <--

propertyType
The type of property being fetched. <--

property
Property, if ICAGetPropertyByType returns successfully. -->

propertyInfo
Property information for 'property', if ICAGetPropertyByType returns successfully. -->

Availability: Introduced in Mac OS X v10.0, but later deprecated in Mac OS X v10.5.

ICAGetPropertyCountPB

typedef struct ICAGetPropertyCountPB { 
    ICAHeader header; 
    ICAObject object; 
    UInt32 coun