usb.jphoto
Class BaselineInitiator

java.lang.Object
  |
  +--usb.jphoto.NameFactory
        |
        +--usb.jphoto.BaselineInitiator

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

Initiator

public class BaselineInitiator

extends NameFactory

implements java.lang.Runnable

This initiates interactions with USB devices, supporting only mandatory PTP-over-USB operations; both "push" and "pull" modes are supported. Note that there are some operations that are mandatory for "push" responders and not "pull" ones, and vice versa. A subclass adds additional standardized operations, which some PTP devices won't support. All low level interactions with the device are done by this class, including especially error recovery.

The basic sequence of operations for any PTP or ISO 15470 initiator (client) is: acquire the device; wrap it with this driver class (or a subclass); issue operations; close device. PTP has the notion of a (single) session with the device, and until you have an open session you may only invoke getDeviceInfo() and openSession() operations. Moreover, devices may be used both for reading images (as from a camera) and writing them (as to a digital picture frame), depending on mode support.

Note that many of the IOExceptions thrown here are actually going to be usb.core.USBException values. That may help your application level recovery processing. You should assume that when any IOException is thrown, your current session has been terminated.

See Also:

Initiator

Constructor Summary

BaselineInitiator(usb.core.Device dev)
Constructs a class driver object, if the device supports operations according to Annex D of the PTP specification.

BaselineInitiator(usb.core.Interface intf_arg)
Constructs a class driver from an interface asserted to conform fully to Annex D of the PTP specification.

Method Summary

void	close() Releases USB resources so that some other program can access the interface this class previously interacted with.
void	closeSession() Issues a CloseSession command to the device; may be used with all responders.
void	fillObject(int handle, Data data) Fills the data object using the object identified by a given handle.
protected void	finalize() Tries to clean up if you forget to call close.
DeviceInfo	getDeviceInfo() Returns the last cached copy of the device info, or returns a newly cached copy.
DeviceInfo	getDeviceInfoUncached() Issues a GetDeviceInfo command to the device; may be used with all responders.
int	getNumObjects(int storageID, int typeFilter, int association) Returns the number of objects in the specified association on the specified store.
Data	getObject(int handle) Returns the data for the object identified by a given handle.
int[]	getObjectHandles(int store, int code, int association) Returns an array of object handles in the store (or stores) specified.
ObjectInfo	getObjectInfo(int handle) Returns information about the object identified by a given handle.
java.lang.String	getPortIdentifier() Returns a port identifier string for this device; use these to address devices, they correspond to the hub port to which a device is attached.
static usb.core.Interface	getPtpInterface(usb.core.Device dev) This function returns a PTP interface for a device, or null if the device has none.
int	getSessionId() Returns the ID of the PTP sesssion in use; initiator only keep one open session at a time, or zero if there's no session.
int[]	getStorageIDs() Returns an array of storage ids for the device; may be used with all responders.
StorageInfo	getStorageInfo(int store) Issues a GetStorageInfo command to the device; may be used with all responders.
Data	getThumb(int handle) Returns the thumbnail for the image identified by a given handle.
boolean	isPull() Returns true iff the associated responder supports "pull mode", reading objects from the device.
boolean	isPush() Returns true iff the associated responder supports "push mode", sending objects to the device.
void	openSession() Issues an OpenSession command to the device; may be used with all responders.
void	reset() Sends a USB level CLASS_DEVICE_RESET control message.
void	run() Makes the invoking Thread read and report events reported by the PTP responder, until the Initiator is closed.
void	sendObject(Data obj) Sends the object identified in a successful preceding sendObjectInfo call.
Response	sendObjectInfo(ObjectInfo info, int storage, int parent) Sends object metadata, in preparation for sending the object described by this data.
protected Response	transact(Command command, Data data) Performs a PTP transaction.
protected Response	transact0(int code, Data data) Performs a PTP transaction, passing zero command parameters.
protected Response	transact1(int code, Data data, int p1) Performs a PTP transaction, passing one command parameter.
protected Response	transact2(int code, Data data, int p1, int p2) Performs a PTP transaction, passing two command parameters.
protected Response	transact3(int code, Data data, int p1, int p2, int p3) Performs a PTP transaction, passing three command parameters.

Methods inherited from class usb.jphoto.NameFactory

getEventString, getFormatString, getOpcodeString, getPropertyName, getResponseString

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BaselineInitiator

public BaselineInitiator(usb.core.Device dev)
                  throws java.io.IOException

Constructs a class driver object, if the device supports operations according to Annex D of the PTP specification.

Parameters:

dev - the first PTP interface will be used

Throws:

java.lang.IllegalArgumentException - if the device has no Digital Still Imaging Class or PTP interfaces

BaselineInitiator

public BaselineInitiator(usb.core.Interface intf_arg)
                  throws java.io.IOException

Constructs a class driver from an interface asserted to conform fully to Annex D of the PTP specification.

Parameters:

intf_arg - the PTP interface to be used

Throws:

java.lang.IllegalArgumentException - if the interface is null or doesn't provide the necessary endpoints.

Method Detail

getPtpInterface

public static usb.core.Interface getPtpInterface(usb.core.Device dev)

This function returns a PTP interface for a device, or null if the device has none.

close

public void close()
           throws java.io.IOException

Releases USB resources so that some other program can access the interface this class previously interacted with. You may wish to separately close the device.

finalize

protected void finalize()

Tries to clean up if you forget to call close.

Overrides:

finalize in class java.lang.Object

getPortIdentifier

public java.lang.String getPortIdentifier()

Returns a port identifier string for this device; use these to address devices, they correspond to the hub port to which a device is attached. Bus addresses change dynamically, so applications shouldn't use them.

isPull

public boolean isPull()

Returns true iff the associated responder supports "pull mode", reading objects from the device. Example "pull mode" devices include digital cameras and other image capture devices, as well as image archives updated in "push mode".

isPush

public boolean isPush()

Returns true iff the associated responder supports "push mode", sending objects to the device. Example "push mode" devices include printers, picture frames, web servers (though not with USB!), and other types of image archives.

getDeviceInfo

public DeviceInfo getDeviceInfo()
                         throws java.io.IOException

Returns the last cached copy of the device info, or returns a newly cached copy.

See Also:

getDeviceInfoUncached()

getSessionId

public int getSessionId()

Returns the ID of the PTP sesssion in use; initiator only keep one open session at a time, or zero if there's no session.

reset

public void reset()
           throws java.io.IOException

Sends a USB level CLASS_DEVICE_RESET control message. All PTP-over-USB devices support this operation. This is documented to clear stalls and camera-specific suspends, flush buffers, and close the current session.

TO BE DETERMINED: How does this differ from a bulk protocol ResetDevice command? That command is documented as very similar to this class operation. Ideally, only this control request will ever be used, since it works even when the bulk channels are halted.

run

public void run()

Makes the invoking Thread read and report events reported by the PTP responder, until the Initiator is closed.

Specified by:

run in interface java.lang.Runnable

getDeviceInfoUncached

public DeviceInfo getDeviceInfoUncached()
                                 throws java.io.IOException

Issues a GetDeviceInfo command to the device; may be used with all responders. This is the only generic PTP command that may be issued both inside or outside of a session.

openSession

public void openSession()
                 throws java.io.IOException

Issues an OpenSession command to the device; may be used with all responders. PTP-over-USB doesn't seem to support multisession operations; you must close a session before opening a new one.

closeSession

public void closeSession()
                  throws java.io.IOException

Issues a CloseSession command to the device; may be used with all responders.

getStorageIDs

public int[] getStorageIDs()
                    throws java.io.IOException

Returns an array of storage ids for the device; may be used with all responders.

getStorageInfo

public StorageInfo getStorageInfo(int store)
                           throws java.io.IOException

Issues a GetStorageInfo command to the device; may be used with all responders.

Parameters:

store - either ~0 to indicate all media, or the ID for some particular store.

getNumObjects

public int getNumObjects(int storageID,
                         int typeFilter,
                         int association)
                  throws java.io.IOException

Returns the number of objects in the specified association on the specified store. Push-only responders don't need to support this operation.

Parameters:

storageID - either ~0 to indicate all media, or the ID for some particular store.

typeFilter - either ~0 to indicate all image objects, zero to indicate all objects, or some specific object format code. Not all responders support such filtering.

association - zero, or the object handle for some association

getObjectHandles

public int[] getObjectHandles(int store,
                              int code,
                              int association)
                       throws java.io.IOException

Returns an array of object handles in the store (or stores) specified. Push-only responders don't need to support this operation.

Parameters:

store - identifies the storage ID; or ~0 to identify all accessible storage.

code - either zero, or ~0 to request only images be returned, or else some format code to be used to filter the handles before they are returned.

association - either zero, or ~0 to specify the root of a store; or else an association handle.

getObjectInfo

public ObjectInfo getObjectInfo(int handle)
                         throws java.io.IOException

Returns information about the object identified by a given handle. Push-only responders don't need to support this operation.

Parameters:

handle - object handle from the current session

getObject

public Data getObject(int handle)
               throws java.io.IOException

Returns the data for the object identified by a given handle. Push-only responders don't need to support this operation.

Parameters:

handle - object handle from the current session

See Also:

fillObject(int, usb.jphoto.Data)

fillObject

public void fillObject(int handle,
                       Data data)
                throws java.io.IOException

Fills the data object using the object identified by a given handle. Push-only responders don't need to support this operation.

This differs from getObject in that the data object is supplied by the caller. Such objects may specialized behaviors, including in particular reducing in-memory buffering for large objects.

Parameters:

handle - object handle from the current session

getThumb

public Data getThumb(int handle)
              throws java.io.IOException

Returns the thumbnail for the image identified by a given handle. Push-only responders don't need to support this operation.

Parameters:

handle - object handle from the current session

sendObjectInfo

public Response sendObjectInfo(ObjectInfo info,
                               int storage,
                               int parent)
                        throws java.io.IOException

Sends object metadata, in preparation for sending the object described by this data. Pull-only responders don't need to support this operation.

Parameters:

info - information about the object; fields in this dataset are interpreted with respect to the initiator (for example, initiator's storage id)

storage - desired responder storage id for the object; or zero indicating the responder should choose one

parent - responder object handle for object's parent; ~0 indicating the root of that object store; or zero indicating the responder should choose.

Returns:

response must be examined by caller; getCode() indicates command status, and if it's "Response.OK" then the positional parameters hold data used when transferring hierarchies.

See Also:

sendObject(usb.jphoto.Data)

sendObject

public void sendObject(Data obj)
                throws java.io.IOException

Sends the object identified in a successful preceding sendObjectInfo call. Pull-only responders don't need to support this operation.

See Also:

sendObjectInfo(usb.jphoto.ObjectInfo, int, int)

transact0

protected Response transact0(int code,
                             Data data)
                      throws java.io.IOException

Performs a PTP transaction, passing zero command parameters.

Parameters:

code - the command code

data - data to be sent or received; or null

Returns:

response; check for code Response.OK before using any positional response parameters

transact1

protected Response transact1(int code,
                             Data data,
                             int p1)
                      throws java.io.IOException

Performs a PTP transaction, passing one command parameter.

Parameters:

code - the command code

data - data to be sent or received; or null

p1 - the first positional parameter

Returns:

response; check for code Response.OK before using any positional response parameters

transact2

protected Response transact2(int code,
                             Data data,
                             int p1,
                             int p2)
                      throws java.io.IOException

Performs a PTP transaction, passing two command parameters.

Parameters:

code - the command code

data - data to be sent or received; or null

p1 - the first positional parameter

p2 - the second positional parameter

Returns:

response; check for code Response.OK before using any positional response parameters

transact3

protected Response transact3(int code,
                             Data data,
                             int p1,
                             int p2,
                             int p3)
                      throws java.io.IOException

Performs a PTP transaction, passing three command parameters.

Parameters:

code - the command code

data - data to be sent or received; or null

p1 - the first positional parameter

p2 - the second positional parameter

p3 - the third positional parameter

Returns:

response; check for code Response.OK before using any positional response parameters

transact

protected Response transact(Command command,
                            Data data)
                     throws java.io.IOException

Performs a PTP transaction. This is normally used only to ensure that vendor-specific command names show up nicely in diagnostics, by providing a subclassed Command (and likely Data as well).

Parameters:

command - the command block

data - data to be sent or received; or null

Returns:

response; check for code Response.OK before using any positional response parameters