ICAApplication.h

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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

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

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

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

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.

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.

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.

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.

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.

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

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

Fields

header

See description for ICAHeader. <->

sessionID

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

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.

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. -->

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. -->

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. -->

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.

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.

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

Fields

header

See description for ICAHeader. <-->

object

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

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.

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.

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.

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.

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.

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.

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.

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

Fields

header

See description for ICAHeader. <-->

object

An object whose number of properties is being requested by calling ICAGetPropertyCount. <--

count

Number of properties returned by ICAGetPropertyCount, 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.

typedef struct ICAGetPropertyDataPB { 
    ICAHeader header; 
    ICAProperty property; 
    UInt32 startByte; 
    UInt32 requestedSize; 
    void *dataPtr; 
    UInt32 actualSize; 
    OSType dataType; 
} ICAGetPropertyDataPB;  

Fields

header

See description for ICAHeader. <-->

property

Property whose data is being fetched. <--

startByte

Offset into 'dataPtr' from where the fetched data should be written. <--

requestedSize

Requested size of data in bytes. <--

dataPtr

A buffer to receive the data. <--

actualSize

Actual size of data written to dataPtr. -->

dataType

Type of data fetched. -->

Availability

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

typedef struct ICAGetPropertyInfoPB { 
    ICAHeader header; 
    ICAProperty property; 
    ICAPropertyInfo propertyInfo; 
} ICAGetPropertyInfoPB;  

Fields

header

See description for ICAHeader. <-->

property

Property whose information is being fetched. <--

propertyInfo

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

Availability

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

typedef struct ICAGetPropertyRefConPB { 
    ICAHeader header; 
    ICAProperty property; 
    UInt32 propertyRefCon; 
} ICAGetPropertyRefConPB;  

Fields

header

See description for ICAHeader. <-->

property

A property whos associated refcon value is being fetched. <--

propertyRefCon

The refcon value, if ICAGetPropertyRefCon returns successfully. -->

Availability

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

typedef struct ICAGetRootOfObjectPB { 
    ICAHeader header; 
    ICAObject object; 
    ICAObject rootObject; 
    ICAObjectInfo rootInfo; 
} ICAGetRootOfObjectPB;  

Fields

header

See description for ICAHeader. <-->

object

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

rootObject

Root object of the object hierarchy, if ICAGetRootOfObject returns successfully. -->

rootInfo

Object information for the root object, if ICAGetRootOfObject returns successfully. -->

Availability

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

typedef struct ICAGetRootOfPropertyPB { 
    ICAHeader header; 
    ICAProperty property; 
    ICAObject rootObject; 
    ICAObjectInfo rootInfo; 
} ICAGetRootOfPropertyPB;  

Fields

header

See description for ICAHeader. <-->

property

A property whose parent is being fetched. <--

rootObject

Root object of the hierarchy in which the parent object of property is found, if ICAGetRootOfProperty returns successfully. -->

rootInfo

Information about 'rootObject', if ICAGetRootOfProperty returns successfully. -->

Availability

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

typedef struct ICAHeader { 
    ICAError err; 
    unsigned long refcon; 
} ICAHeader;  

Fields

err

Error returned by an API. -->

refcon

An arbitrary refcon value passed to the callback. <--

Discussion

This is the first field in all parameter blocks used by APIs defined in ICAApplication.h. Type of parameter passed to a callback function used by APIs defined in ICAApplication.h. The parameter for the completion proc should to be casted to an appropriate type such as ICAGetChildCountPB* for it to be useful.

typedef struct ICAImportImagePB { 
    ICAHeader header; 
    ICAObject deviceObject; 
    UInt32 flags; 
    CFArrayRef supportedFileTypes; 
    ICAImportFilterProc filterProc; 
    CFArrayRef *importedImages; 
} ICAImportImagePB;  

Fields

header

See description for ICAHeader. <->

deviceObject

Object ID of a camera or scanner device. Set this to NULL to ge the default behavior: (a) if no device is connected, a panel saying that there\xD5s no device connected is displayed, (b) if a single device is connected, an appropriate user interface to access that device will be displayed, (c) if several devices are connected, a device selector panel will be displayed. <--

flags

One or more flags (combined with an OR operator) defined in ImportImage flags enum. <--

supportedFileTypes

An array of file extension strings such as "jpg", "tif", etc., that are of interest to the calling application. Set to NULL to display all files. <--

filterProc

Specify a filter proc to that will be called for each file before it is displayed in the user interface. <--

importedImages

Returns an array of CFDataRefs for the imported images if the kICADownloadAndReturnPathArray flag is not specified. Otherwise returns an array of CFStringRefs holding the paths of the images that are downloaded. -->

typedef struct ICALoadDeviceModulePB { 
    ICAHeader header; 
    CFDictionaryRef paramDictionary; 
} ICALoadDeviceModulePB;  

Fields

header

See description for ICAHeader. <->

paramDictionary

<-- A parameter dictionary with sufficient key-value pairs to load a device module. This dictionary itself or the information provided in this dictionary will be sent to the device module.

typedef struct ICAMessage { 
    OSType messageType; 
    UInt32 startByte; 
    void *dataPtr; 
    UInt32 dataSize; 
    OSType dataType; 
} ICAMessage;  

Fields

messageType

A message type. e.g., kICAMessageCameraCaptureNewImage. <--

startByte

Offset in dataPtr from where data access for read/write should occur. <--

dataPtr

A pointer to a data buffer. <--

dataSize

Size of data. <--

dataType

Type of data. <--

typedef struct ICAObjectInfo { 
    OSType objectType; 
    OSType objectSubtype; 
} ICAObjectInfo;  

Fields

objectType

An object type, e.g., kICAFile.

objectSubtype

An object subtype, e.g., kICAFileImage.

typedef struct ICAObjectSendMessagePB { 
    ICAHeader header; 
    ICAObject object; 
    ICAMessage message; 
    UInt32 result; 
} ICAObjectSendMessagePB;  

Fields

header

See description for ICAHeader. <-->

object

A target object for the message sent by ICAObjectSendMessage. <--

message

One of the messages define above. <--

result

A message specific result is returned here. -->

typedef struct ICAOpenSessionPB { 
    ICAHeader header; 
    ICAObject deviceObject; 
    ICASessionID sessionID; 
} ICAOpenSessionPB;  

Fields

header

See description for ICAHeader. <->

deviceObject

A camera object. <--

sessionID

A session ID of the opened session. -->

typedef struct ICAPropertyInfo { 
    OSType propertyType; 
    OSType dataType; 
    UInt32 dataSize; 
    UInt32 dataFlags; 
} ICAPropertyInfo;  

Fields

propertyType

A property type.

dataType

A property subtype.

dataSize

TBD

dataFlags

TBD

typedef struct ICAPTPEventDataset { 
    UInt32 dataLength; 
    UInt16 containerType; // should be 0x0004 for event 
    UInt16 eventCode; 
    UInt32 transactionID; 
    UInt32 params[3]; // up to 3 params. # of params = (dataLength - 12)/4 
} ICAPTPEventDataset;  

Fields

dataLength

Data length in bytes

containerType

PTP container type

eventCode

PTP event code

transactionID

PTP transaction ID

params

PTP params. The number of params should be (dataLength - 12)/4

typedef struct ICAPTPPassThroughPB { 
    UInt32 commandCode; 
    UInt32 resultCode; 
    UInt32 numOfInputParams; 
    UInt32 numOfOutputParams; 
    UInt32 params[4]; 
    UInt32 dataUsageMode; 
    UInt32 flags; 
    UInt32 dataSize; 
    UInt8 data[1]; 
} ICAPTPPassThroughPB;  

Fields

commandCode

PTP command code (including vendor specific) <--

resultCode

PTP response code -->

numOfInputParams

Number of valid parameters to be sent to device <--

numOfOutputParams

Number of valid parameters expected from device <--

params

PTP parameters (command specific / optional) <->

dataUsageMode

One of (kICACameraPassThruSend, kICACameraPassThruReceive, kICACameraPassThruNotUsed) <--

flags

Not used currently

dataSize

Size of data block <->

data

Data block <->

typedef struct ICARegisterEventNotificationPB { 
    ICAHeader header; 
    ICAObject object; 
    OSType notifyType; 
    ICACompletion notifyProc; 
} ICARegisterEventNotificationPB;  

Fields

header

See description for ICAHeader. <-->

object

An object about which notifications are requested. <->

notifyType

Notification type of interest. <->

notifyProc

A callback function to receive the notifications. <--

Discussion

Use this parameter block to receive basic notifications.

Availability

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

typedef struct ICARegisterForEventNotificationPB { 
    ICAHeader header; 
    ICAObject objectOfInterest; 
    CFArrayRef eventsOfInterest; 
    ICANotification notificationProc; 
    CFDictionaryRef options; 
} ICARegisterForEventNotificationPB;  

Fields

header

See description for ICAHeader. <->

objectOfInterest

An object about which notifications are requested. <--

eventsOfInterest

An array of notification types of interest. <--

notificationProc

A callback function to receive the notifications. <--

options

Set options to NULL. This parameter is intended for future use. <--

Discussion

Use this parameter structure to specify a set of events associated with an object about which notifications should be sent to the specified notification function.

typedef struct ICAScannerCloseSessionPB { 
    ICAHeader header; 
    ICAScannerSessionID sessionID; 
} ICAScannerCloseSessionPB;  

Fields

header

See description for ICAHeader. <->

sessionID

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

typedef struct ICAScannerGetParametersPB { 
    ICAHeader header; 
    ICAScannerSessionID sessionID; 
    CFMutableDictionaryRef theDict; 
} ICAScannerGetParametersPB;  

Fields

header

See description for ICAHeader. <->

sessionID

A session ID of the scanner whose parameters are being fetched. <--

theDict

A dictionary containing the parameters. -->

typedef struct ICAScannerInitializePB { 
    ICAHeader header; 
    ICAScannerSessionID sessionID; 
} ICAScannerInitializePB;  

Fields

header

See description for ICAHeader. <->

sessionID

A session ID of the scanner to be initialized. <--

typedef struct ICAScannerOpenSessionPB { 
    ICAHeader header; 
    ICAObject object; 
    ICAScannerSessionID sessionID; 
} ICAScannerOpenSessionPB;  

Fields

header

See description for ICAHeader. <->

object

A scanner object. <--

sessionID

A session ID of the opened session. -->

typedef struct ICAScannerSetParametersPB { 
    ICAHeader header; 
    ICAScannerSessionID sessionID; 
    CFMutableDictionaryRef theDict; 
} ICAScannerSetParametersPB;  

Fields

header

See description for ICAHeader. <->

sessionID

A session ID of the scanner whose parameters are being set. <--

theDict

A dictionary containing the parameters. <--

typedef struct ICAScannerStartPB { 
    ICAHeader header; 
    ICAScannerSessionID sessionID; 
} ICAScannerStartPB;  

Fields

header

See description for ICAHeader. <->

sessionID

A session ID of the scanner that should start scanning. <--

typedef struct ICAScannerStatusPB { 
    ICAHeader header; 
    ICAScannerSessionID sessionID; 
    UInt32 status; 
} ICAScannerStatusPB;  

Fields

header

See description for ICAHeader. <->

sessionID

A session ID of the scanner whose status is being fetched. <--

status

A status value. -->

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

Fields

header

See description for ICAHeader. <-->

object

An object whose associated refcon value is being set by calling ICASetObjectRefCon. <--

objectRefCon

The refcon value. <--

Availability

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

typedef struct ICASetPropertyDataPB { 
    ICAHeader header; 
    ICAProperty property; 
    UInt32 startByte; 
    void *dataPtr; 
    UInt32 dataSize; 
    OSType dataType; 
} ICASetPropertyDataPB;  

Fields

header

See description for ICAHeader. <-->

property

Property whose data is being fetched. <--

startByte

Offset into 'dataPtr' from where the data being sent is found. <--

dataPtr

A buffer holding data being sent. <--

dataSize

Size of data sent in dataPtr. <--

dataType

Type of data sent. <--

Availability

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

typedef struct ICASetPropertyRefConPB { 
    ICAHeader header; 
    ICAProperty property; /* <-- */
    UInt32 propertyRefCon; /* <-- */
} ICASetPropertyRefConPB;  

Fields

header

See description for ICAHeader. <-->

property

A property whos associated refcon value is being set. <--

propertyRefCon

The refcon value. <--

Availability

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

typedef struct ICAThumbnail { 
    UInt32 width; 
    UInt32 height; 
    UInt32 dataSize; 
    UInt8 data[1]; 
} ICAThumbnail;  

Fields

width

Thumbnail width in pixels.

height

Thumbnail height in pixels.

dataSize

Thumbnail size in bytes. This should be 3*height*width for thumbnails without alpha channel and should be 4*height*width for thumbnails with alpha channel. The alpha channel is always stored at the end of the buffer.

data

Thumbnail buffer of 8-bit RGB data (RGBRGBRGB...)

Discussion

This type is deprecated. Use ICACopyObjectThumbnail call to receive thumbnail in JPG, TIFF or PNG format.

Availability

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

typedef struct ICAUnloadDeviceModulePB { 
    ICAHeader header; 
    ICAObject deviceObject; 
} ICAUnloadDeviceModulePB;  

Fields

header

See description for ICAHeader. <->

deviceObject

<-- A device ICAObject.

typedef struct ICAUploadFilePB { 
    ICAHeader header; 
    ICAObject parentObject; 
    FSRef *fileFSRef; 
    UInt32 flags; 
} ICAUploadFilePB;  

Fields

header

See description for ICAHeader. <->

parentObject

<-> An ICAObject corresponding to a folder on the device. The device will store the uploaded file inside this folder if possible.

fileFSRef

<-- An FSRef for the file to be uploaded to the device.

flags

<-- One of the flags defined above.

Enumerations

enum { 
    kICAButtonScan = 'scan', 
    kICAButtonCopy = 'copy', 
    kICAButtonEMail = 'mail', 
    kICAButtonWeb = 'web ' 
};  

Constants

kICAButtonScan

Scan button.

kICAButtonCopy

Copy button.

kICAButtonEMail

Email button.

kICAButtonWeb

Web button.

Discussion

Buttons types associated with buttons on a scanner.

enum { 
    kICATypeUInt8 = 'ui08', 
    kICATypeUInt16 = 'ui16', 
    kICATypeUInt32 = 'ui32', 
    kICATypeUInt64 = 'ui64', 
    kICATypeSInt16 = 'si16', 
    kICATypeSInt32 = 'si32', 
    kICATypeSInt64 = 'si64', 
    kICATypeFloat = 'floa', 
    kICATypeFixed = 'sing', 
    kICATypeBoolean = 'bool', 
    kICATypeString = 'TEXT', 
    kICATypeData = 'data', 
    kICATypeThumbnail = 'thum' 
};  

Constants

kICATypeUInt8

UInt8.

kICATypeUInt16

UInt16.

kICATypeUInt32

UInt32.

kICATypeUInt64

UInt64.

kICATypeSInt16

SInt16.

kICATypeSInt32

SInt32.

kICATypeSInt64

SInt64.

kICATypeFloat

float.

kICATypeFixed

IEEE 32-bit floating point.

kICATypeBoolean

Boolean.

kICATypeString

Char string.

kICATypeData

void *.

kICATypeThumbnail

ICAThumbnail.

Discussion

Definition of data types; these are mapped to AppleEvent types.

enum { 
    kICACommunicationErr = -9900, 
    kICADeviceNotFoundErr = -9901, 
    kICADeviceNotOpenErr = -9902, 
    kICAFileCorruptedErr = -9903, 
    kICAIOPendingErr = -9904, 
    kICAInvalidObjectErr = -9905, 
    kICAInvalidPropertyErr = -9906, 
    kICAIndexOutOfRangeErr = -9907, 
    kICAPropertyTypeNotFoundErr = -9908, 
    kICACannotYieldDevice = -9909, 
    kICADataTypeNotFoundErr = -9910, 
    kICADeviceMemoryAllocationErr = -9911, 
    kICADeviceInternalErr = -9912, 
    kICADeviceInvalidParamErr = -9913, 
    kICADeviceAlreadyOpenErr = -9914, 
    kICADeviceLocationIDNotFoundErr = -9915, 
    kICADeviceGUIDNotFoundErr = -9916, 
    kICADeviceIOServicePathNotFoundErr = -9917, 
    kICADeviceUnsupportedErr = -9918, 
    kICAFrameworkInternalErr = -9919, 
    kICAExtensionInternalErr = -9920, 
    kICAInvalidSessionErr = -9921 
};  

Constants

kICACommunicationErr

An error occurred in communication between different components of Image Capture framework.

kICADeviceNotFoundErr

The specified device is not found.

kICADeviceNotOpenErr

The specified device is not open.

kICAFileCorruptedErr

Encountered a corrupt file.

kICAIOPendingErr

There is a pending I/O.

kICAInvalidObjectErr

The specified object is invalid.

kICAInvalidPropertyErr

The specified property is invalid.

kICAIndexOutOfRangeErr

The specified index is out of range.

kICAPropertyTypeNotFoundErr

A property with the specified property type is not found.

kICACannotYieldDevice

The device module cannot yield the specified device to the requestor.

kICADataTypeNotFoundErr

Data with the specified data type is not found.

kICADeviceMemoryAllocationErr

The device module encountered a memory allocation error.

kICADeviceInternalErr

The device module encountered an unspecifed error.

kICADeviceInvalidParamErr

At least one of the parameters passed to the device module is invalid.

kICADeviceAlreadyOpenErr

The specified device is already open.

kICADeviceLocationIDNotFoundErr

The specified USB Location ID is not found.

kICADeviceGUIDNotFoundErr

The specified FireWire GUID is not found.

kICADeviceIOServicePathNotFoundErr

The specified IOService path is not found.

kICAFrameworkInternalErr

Image Capture Framework encountered an error.

kICAExtensionInternalErr

Image Capture Extension encountered an error.

kICAInvalidSessionErr

The specified session is not valid.

Discussion

Definition of error codes returned by Image Capture framework

enum { 
    kICAEventClassPTPStandard = 'PTPs', 
    kICAEventClassPTPVendor = 'PTPv', 
    kEventClassPTPStandard = 'PTPs', 
    kEventClassPTPVendor = 'PTPv' 
};  

Constants

kICAEventClassPTPStandard

PTP standard event.

kICAEventClassPTPVendor

PTP vendor-specific event.

kEventClassPTPStandard

PTP standard event. Deprecated in 10.5. Use kICAEventClassPTPStandard instead.

kEventClassPTPVendor

PTP vendor-specific event. Deprecated in 10.5. Use kICAEventClassPTPVendor instead.

Discussion

Event class returned in extended event notifications. Deprecated in 10.5

enum { 
    kICAStartAtBeginning = 0, 
    kICAEntireLength = -1 
};  

Constants

kICAStartAtBeginning

Start reading from the beginning.

kICAEntireLength

Read all data.

Discussion

Use one of these values when reading property data using partial reads.

enum { 
    kDeleteAfterDownload = 0x00000001, 
    kCreateCustomIcon = 0x00000002, 
    kAddMetaDataToFinderComment = 0x00000004, 
    kAdjustCreationDate = 0x00000008, 
    kSetFileTypeAndCreator = 0x00000010, 
    //kEmbedColorSyncProfile = 0x00000020, 
    kRotateImage = 0x00000040, 
    kDontEmbedColorSyncProfile = 0x00000080 
};  

Constants

kDeleteAfterDownload

Delete file after a successful download.

kCreateCustomIcon

Create a custom icon for Finder.

kAddMetaDataToFinderComment

Add basic metadata to finder comment field.

kAdjustCreationDate

Set creation date of the downloaded file same as the creation date for the file as reported by the device.

kSetFileTypeAndCreator

Set 4-char file type and creator code.

kRotateImage

Rotate the image.

kDontEmbedColorSyncProfile

Embed ColorSync profile to the image if one was not already embedded.

Discussion

Use any combination of these values when downloading a file.

enum { 
    kICACameraPassThruSend = 0, 
    kICACameraPassThruReceive = 1, 
    kICACameraPassThruNotUsed = 2 
};  

Constants

kICACameraPassThruSend

Use this constant when sending data to a device using a pass-through command.

kICACameraPassThruReceive

Use this constant when receiving data from a device using a pass-through command.

kICACameraPassThruNotUsed

Use this constant when using a pass-through command that doesn't involve sending or receiving data.

Discussion

Flag values that can be used in ICAUploadFilePB parameter block.

enum { 
    kICAMessageConnect = 'open', 
    kICAMessageDisconnect = 'clos', 
    kICAMessageReset = 'rese', 
    kICAMessageCheckDevice = 'chkd', 
    kICAMessageCameraReadClock = 'rclk', 
    kICAMessageGetLastButtonPressed = 'btn?', 
    kMessageGetEventData = 'mged', // Deprecated in 10.5 
    kICAMessageGetEventData = 'mged', 
    kICAMessageDeviceYield = 'yiel', 
    kICAMessageCameraPassThrough = 'pass' 
};  

Constants

kICAMessageConnect

Connect to device.

kICAMessageDisconnect

Disconnect device.

kICAMessageReset

Reset device.

kICAMessageCheckDevice

Check device.

kICAMessageCameraReadClock

Read clock from device.

kICAMessageGetLastButtonPressed

Get last button pressed on the device (scanner).

kICAMessageGetEventData

Get data associated with an event.

kMessageGetEventData

Get data associated with an event. This is deprecated in favor of kICAMessageGetEventData.

kICAMessageDeviceYield

Yield device. Image Capture framework yields a device so that the sender of the message can directly communicate with the device.

Discussion

Definition of ICAMessage types.

enum { 
    kICADevice = 'icdv', 
    kICADeviceCamera = 'cmra', 
    kICADeviceScanner = 'scan', 
    kICADeviceMFP = 'mfp ', 
    kICADevicePhone = 'phon', 
    kICADevicePDA = 'pda ', 
    kICADeviceOther = 'doth', 
    kICAList = 'objl', 
    kICADirectory = 'dire', 
    kICAFile = 'file', 
    kICAFileImage = 'imag', 
    kICAFileMovie = 'moov', 
    kICAFileAudio = 'audo', 
    kICAFileFirmware = 'firm', 
    kICAFileOther = 'othe' 
};  

Constants

kICADevice

Object is a device supported by Image Capture framework.

kICADeviceCamera

Object is a camera.

kICADeviceScanner

Object is a scanner.

kICADeviceMFP

Object is a multi-function peripheral.

kICADevicePhone

Object is a camera phone.

kICADevicePDA

Object is a personal digital assistant.

kICADeviceOther

Object is a device supported by Image Capture framework, but of unknown subtype.

kICAList

Object is a device list.

kICADirectory

Object is a directory.

kICAFile

Object is a file.

kICAFileImage

Object is an image file.

kICAFileMovie

Object is a movie file.

kICAFileAudio

Object is an audio file.

kICAFileFirmware

Object is a firmware file.

kICAFileOther

Object is a generic file.

Discussion

Definition of ICAObject types and subtypes

enum { 
    kICAProperty = 'prop', 
    kICAPropertyImageWidth = '0100', 
    kICAPropertyImageHeight = '0101', 
    kICAPropertyImageBitDepth = '0102', 
    kICAPropertyImageDPI = '011A', 
    kICAPropertyImageExposureTime = '829A', 
    kICAPropertyImageFNumber = '829D', 
    kICAPropertyImageDateOriginal = '9003', 
    kICAPropertyImageDateDigitized = '9004', 
    kICAPropertyImageShutterSpeed = '9201', 
    kICAPropertyImageAperture = '9202', 
    kICAPropertyImageFlash = '9209', 
    kICAPropertyColorSpace = 'A001', 
    kICAPropertyImageFilename = 'ifil', 
    kICAPropertyImageSize = 'isiz', 
    kICAPropertyImageData = 'idat', 
    kICAPropertyImageThumbnail = 'thum', 
    kICAPropertyColorSyncProfile = 'prof' 
};  

Constants

kICAProperty

Generic property type; for images, refer to 'Digital Still Camera Image File Format Standard' Exif Version 2.1 section 2.6.4. and 2.6.5.

kICAPropertyImageWidth

Image width.

kICAPropertyImageHeight

Image height.

kICAPropertyImageBitDepth

Image bit-depth.

kICAPropertyImageDPI

Image DPI.

kICAPropertyImageExposureTime

Image exposure time.

kICAPropertyImageFNumber

Image f-Number.

kICAPropertyImageDateOriginal

Original date & time of an object; value associated with this property is a null-terminated string conforming to format "YYYY:MM:DD hh:mm:ss".

kICAPropertyImageDateDigitized

Digitized date & time of an object; value associated with this property is a null-terminated string conforming to format "YYYY:MM:DD hh:mm:ss".

kICAPropertyImageShutterSpeed

Shutter speed used to capture an image.

kICAPropertyImageAperture

Aperture used to capture an image.

kICAPropertyImageFlash

Indicates whether flash was used to capture an image.

kICAPropertyColorSpace

Color space used to represent an image.

kICAPropertyImageFilename

Filename of an image.

kICAPropertyImageSize

Size of an image in bytes.

kICAPropertyImageData

Data of an image.

kICAPropertyImageThumbnail

Thumbnail of an image.

kICAPropertyColorSyncProfile

ColorSync profile associated with an image.

Discussion

Definition of ICAProperties

enum { 
    kICAEventCancelTransaction = 'ecnt', 
    kICAEventObjectAdded = 'eoba', 
    kICAEventObjectRemoved = 'eobr', 
    kICAEventStoreAdded = 'esta', 
    kICAEventStoreRemoved = 'estr', 
    kICAEventDeviceAdded = 'edea', 
    kICAEventDeviceRemoved = 'eder', 
    kICAEventDevicePropChanged = 'edpc', 
    kICAEventObjectInfoChanged = 'eoic', 
    kICAEventDeviceInfoChanged = 'edic', 
    kICAEventRequestObjectTransfer = 'erot', 
    kICAEventStoreFull = 'estf', 
    kICAEventDeviceReset = 'edvr', 
    kICAEventStorageInfoChanged = 'esic', 
    kICAEventCaptureComplete = 'ecpc', 
    kICAEventUnreportedStatus = 'eurs', 
    kICAExtendedNotificationPB = 'extd', 
    kExtendedNotificationPB = 'extd' 
};  

Constants

kICAEventCancelTransaction

Cancel transaction.

kICAEventObjectAdded

A new object has been added.

kICAEventObjectRemoved

An object has been removed.

kICAEventStoreAdded

A new storage has been added.

kICAEventStoreRemoved

A storage has been removed.

kICAEventDeviceAdded

A new device has been added.

kICAEventDeviceRemoved

A device has been removed.

kICAEventDevicePropChanged

Device property has changed.

kICAEventObjectInfoChanged

Object information has changed.

kICAEventDeviceInfoChanged

Device information has changed.

kICAEventRequestObjectTransfer

Requesting transfer of an object.

kICAEventStoreFull

Store is full.

kICAEventDeviceReset

Device has been reset.

kICAEventStorageInfoChanged

Storage information has changed.

kICAEventCaptureComplete

Image capture has been completed.

kICAEventUnreportedStatus

Unreported status.

kExtendedNotificationPB

Indicates the event notification uses extended notification parameter block.

Discussion

Image Capture event types (Refer to section 12.4 of PTP spec for PTP-specific events). These are deprecated in 10.5.

enum { 
    kICAAllowMultipleImages = 0x00000001, 
    kICADownloadAndReturnPathArray = 0x00000002 
};  

Constants

kICAAllowMultipleImages

Use this constant to allow users to select multiple images in the Import Image dialog.

kICADownloadAndReturnPathArray

Currently not used.

Discussion

Flag values that can be used in ICAImportImagePB parameter block.

enum { 
    kICAPBVersion = 0x00010000 
};  

Constants

kICAPBVersion

Version 1 parameter block.

Discussion

Parameter block version.

enum { 
    kICAFlagReadWriteAccess = 1L << 0, 
    kICAFlagReadAccess = 1L << 1 
};  

Constants

kICAFlagReadWriteAccess

Access for read and write.

kICAFlagReadAccess

Access for read only.

Discussion

Values for PropertyInfo flag.

enum { 
    kICAThumbnailFormatICA = 'ica ', 
    kICAThumbnailFormatJPEG = 'jpeg', 
    kICAThumbnailFormatTIFF = 'tiff', 
    kICAThumbnailFormatPNG = 'png ', 
    kICAThumbnailFormatJPEGAutoRotated = 'JPEG', 
    kICAThumbnailFormatTIFFAutoRotated = 'TIFF', 
    kICAThumbnailFormatPNGAutoRotated = 'PNG ' 
};  

Constants

kICAThumbnailFormatICA

Use this constant to receive a thumbnail in ICAThumbnail structure. Deprecated in 10.5.

kICAThumbnailFormatJPEG

Use this constant to receive a thumbnail in JPEG format.

kICAThumbnailFormatTIFF

Use this constant to receive a thumbnail in TIFF format.

kICAThumbnailFormatPNG

Use this constant to receive a thumbnail in PNG format.

kICAThumbnailFormatJPEGAutoRotated

Use this constant to receive a thumbnail in JPEG format with its orientation matching the full image orientation.

kICAThumbnailFormatTIFFAutoRotated

Use this constant to receive a thumbnail in TIFF format with its orientation matching the full image orientation.

kICAThumbnailFormatPNGAutoRotated

Use this constant to receive a thumbnail in PNG format with its orientation matching the full image orientation.

Discussion

Format alues that can be used in ICACopyObjectThumbnailPB parameter block.

enum { 
    kICAUploadFileAsIs = 0x00000000, 
    kICAUploadFileScaleToFit = 0x00000001 
};  

Constants

kICAUploadFileAsIs

Use this constant to upload a file as is.

kICAUploadFileScaleToFit

Use this constant to upload a file after scaling to fit a specified bounding rect.

Discussion

Flag values that can be used in ICAUploadFilePB parameter block.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11