Message	Windows	MacOSX	MacOS9
General
New	•	•	•
OpenById	•	•	•
OpenByProductName	•	•	•
IsOpen	•	•	•
Close	•	•	•
Write	•	NYI	X
MonitorChanges	•
FindAllUsbDevices	•	•	•
Reading data
Read	•	•	•
NumberOfItemsInReadBuffer	•	NYI	X
ReadPacket	•
NumberOfPacketsInReadBuffer	•
ReadReport	•
DoNotBufferPackets	•
Misc
ShowErrorsAsDialogs	•	•	•
GetVersionString	•	•	•
GetLicensetype	•	•	•
GetDemoDaysRemaining	•	NYI	NYI
privateInstance	•	•	•
privateGlobal	•	•	•

Version release history

New

Command format	new xtra
Description	Standard message to create a new instance
Parameters	objectRef: valid instance of UsbAccessXtra created with
Notes
Return value	A valid object instance or null.
Example	theXtra = new ( xtra"UsbAccessXtra" )

OpenById

Command format	OpenById objectRef me , integer vendorID, integer productID
Description	If you know the device vendor and product ids you can open them with this message. You can use FindUsbDevices to obtain this information.
Parameters	ObjectRef: A valid UsbAccessXtra oject instance vendorID: Number as found by FindAllUsbDevices productID: Number as found by FindAllUsbDevices
Notes
Return value	ok or error
Example

OpenByProductName

Command format	OpenByProductName, objectRef me , string name
Description	Open a connected usb device using the name
Parameters	ObjectRef: A valid UsbAccessXtra oject instance Name: The name of the device
Notes
Return value	ok or Error:
Example	put theXtra.OpenByProductName("TheDonglething")

IsOpen

Command format	IsOpen object objectRef
Description	returns true if a device is open, else false
Parameters	objectRef: valid instance of UsbAccessXtra created with
Notes
Return value	true/false 1/0
Example	put theXtra.isOpen()

Close

Command format	Close object objectRef
Description	Close an open usb device.
Parameters	objectRef: valid instance of UsbAccessXtra created with
Notes
Return value	ok or error
Example	put theXtra.Close()

Write

Command format	Write object objectRef, {any number of strings or lists} *
Description	Write data to the Usb hid device.
Parameters	objectRef: valid instance of UsbAccessXtra created with "new" * : Any number of parameters, each of which must be a string or list
Notes	All Usb devices operate in "blocks" of data. It is the users responsibility to send the correct amount of data. If the Write is called with an incorect amount the xtra fills with random data to bring it to a bock size.
Return value	ok or error
Example	put theXtra.Write("Hello') put theXtra.Write([1,2,3,4,5] put theXtra.Write("Hello",[1,2,3,4]) put theXtra.Write(["Hello",[1,2,3,4]],"[5,6,7,8])

MonitorChanges

Command format	MonitorChanges objectRef me, string lingoFunctionToCall
Description	Monitor the usb bus for connections and disconnections and callback into Director when an event occurs.
Parameters	ObjectRef: A valid UsbAccessXtra object instance lingoFunctionToCall : The name of a lingo function to call when event occurs
Notes	Use "" to disable this feature. The handler is called with one parameter, a list of the status data, eg [#xtraName: "USBAccessXtra", #type: "Device inserted or removed", #id: 71042432]
Return value
Example	theXtra.MonitorChanges("TheHandlerToCall") on TheHandlerToCall data put data end

FindAllUsbDevices

Command format	FindAllUsbDevices object objectRef
Description	Scan through all the Usb hid devices and return info on each
Parameters	objectRef: valid instance of UsbAccessXtra created with
Notes	ONLY HID devices
Return value	A list of devices, each sub list contains
Example	put theXtra.FindUsbDevices()

Read

Command format	Read object objectRef
Description	Read data that has been recieved from the Usb hid device.
Parameters	objectRef: valid instance of UsbAccessXtra created with
Notes
Return value	A list that contains all the recieved data from the device since the last call to Read. [] indicates that there was no data waiting.
Example	put theXtra.Read()

NumberOfItemsInReadBuffer

Command format	NumberOfItemsInReadBuffer object objectRef
Description	Obtain a count of the number of bytes waiting to be read from the input buffer.
Parameters	objectRef: valid instance of UsbAccessXtra created with "new"
Notes
Return value	A number that is the number of bytes wating to be read
Example	put theXtra.NumberOfItemsInReadBuffer()

ReadPacket

Command format	ReadPacket objectRef me
Description	Usb data is transferred in blocks called packets. Often it is preferential to read a packet at a time. This message supports this. The Read message reads all the waiting data and returns them.
Parameters	ObjectRef: A valid UsbAccessXtra oject instance
Notes
Return value	Returns a list containg the data in the packet
Example	put theXtra.ReadPAcket()

NumberOfPacketsInReadBuffer

Command format	NumberOfPacketsInReadBuffer objectRef me
Description	Obtain the number of packets, rather than bytes, waiting in the input buffer
Parameters	ObjectRef: A valid UsbAccessXtra oject instance
Notes
Return value	Returns the number of packets waiting in the input buffer
Example	put theXtra.NumberOfPacketsInReadBuffer()

ReadReport

Command format	ReadReport objectRef me
Description	Read the HID descriptor data
Parameters	ObjectRef: A valid UsbAccessXtra oject instance
Notes
Return value	List of the report data
Example	put theXtra.ReadReport()

DoNotBufferPackets

Command format	DoNotBufferPackets objectRef me
Description	Enable or disable the packet buffering option. When false, all packets are put into the input queue when they arrive. If true then only the latest packet is ever in the input queue. The default value is false
Parameters	ObjectRef: A valid UsbAccessXtra oject instance
Notes
Return value
Example	theXtra.DoNotBufferPackets(true)

ShowErrorsAsDialogs

Command format	ShowErrorsAsDialogs object objectRef, integer truOrFalse
Description	Controls if error dialogs are shwn in addtion to the error return. Turn this off is you want your problem to handle errors without informing the user
Parameters	objectRef: valid instance of UsbAccessXtra created with "new" trueOrFalse: true to turn dialogs on, or false to turn them off
Notes
Return value	"ok" or "Error"
Example	theXtra.ShowErrorsAsDialogs(0)

GetVersionString

Command format	GetVersionString object objectRef
Description	Obtain the version number of the xtra as a string. This may be requested when you are reporting bugs or interacting with PhysicalBits support.
Parameters	objectRef: valid instance of UsbAccessXtra created with "new"
Notes
Return value	A version string.
Example	put theXtra.GetVersionString()

GetLicensetype

Command format	GetLicenseType object objectRef
Description	Returns the license type for this xtra. #Author, #Demo or #Full
Parameters	objectRef: valid instance of UsbAccessXtra created with "new"
Notes
Return value	#Author, #Demo or #Full
Example	put theXtra.GetLicenseType()

GetDemoDaysRemaining

Command format	GetDemoDaysRemaining object me
Description	Returns the number of days remaining on a demo license. Returns 0 if authoring license, or a big number if a full license.
Parameters	object me: The value returned from new
Notes
Return value	Integer number
Example	put theXtra.GetDemoDaysRemaining()

privateInstance

Command format	privateInstance
Description	Private function
Parameters	Private
Notes	for the curious: 0 = invalid: 1 = internal error reporting, 0=off 1=on: 2 = flow control reporting, 0=off 1=on, 0-100 level: 3 = log messages to file, 0=off 1=on, filname:
Return value
Example

privateGlobal

Command format	privateGlobal
Description	Private
Parameters
Notes
Return value
Example

Known Issues

There are no outstanding issues at this time

Version History

Version	Date	Platform	Notes
1.0.8	2006-11-09	wintel	New messages and tidying
1.0.0	2004-07-13	wintel	Initial release for windows only.
1.0.0	2004-12-07	osx	The OSX version of the Xtra requires a seperate library file. It is called HID.bundle. Place it in the root directory, the same as the movie, or use message 'SetOsxLibraryPath'.
1.0.0	2004-12-28	os9	Initial release for os9

---

Conditions of use

In this document Xtra refers to this Xtra, and me refers to Geoff Smith. All rights to the XObject/Xtra are retained by me. The XObject may be used in any MacroMedia Director document for personal use and given to your friends. All documentation must be included when passing on the XObject/Xtra. Unless licensed you may NOT do the following ·distribute for profit without prior permission. ·distribute for profit within a Director presentation without prior permission ·distribute by CD-ROM without prior permission. ·distribute as part of a collection without prior permission ·be used in a public presentation without prior permission. Financial liabilty for this product is limited to the purchase price or $1, whichever is greater. All legal proceeding must be carried out under the auspices of the court of Santa Clara, California, USA. These conditions may be modified at any time. Please refer to the physicalbits website for the latest conditions.