. DirectXtras Home
        Home

DirectCommunication Xtra
Documentation
License Agreement
Licensing Fees
Order Form
DirectConnection Xtra
DirectControl Xtra
DirectEmail Xtra
DirectFTP Xtra
DirectImage Xtra
DirectInteraction Xtra
DirectOS Xtra
DirectSMS Xtra
DirectSound Xtra
DirectTransition Xtra
DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
DirectTTS Xtra
XtrAgent
DirectXport Xtra

SpeechPlugin

Special Discounted Bundles

The Gallery
How To Order
Order Form
Check for Upgrades

Sign in
Change Your Profile

Contact Us
















    .
DirectXtras
Xtra Power for Director & Authorware



DirectCommunication Xtra
 Direct access to serial/parallel ports from Director and Authorware.

Authorware 4.x Compatible Authorware 5.x CompatibleAuthorware 6.x CompatibleAuthorware 7.x CompatibleDirector 5.x Compatible Director 6.x CompatibleDirector 7.x Compatible Director 8.x CompatibleDirector MX CompatibleDirector MX 2004 Compatible Director Shockwave Compatible and Safe     MacOS 8.x and 9.x CompatibleMacOS X CompatibleWindows Compatible   

DirectCommunication Xtra™ Version 2.0 Documentation

Developed by Tomer Berda, DirectXtras Inc.
(C) Copyright 1997-2004.
Last updated: August 20th, 2004.

DirectCommunication Xtra is a cross-platform Scripting Xtra for Macromedia Director, Authorware and Shockwave that provides applications with the ability to communicate with devices connected to the system through the serial port, parallel port or USB serial adapter. Such devices include modems, fax machines, card readers, mini discs, alarm systems, show control systems, laser disc players, telephone response systems, computers and virtually any other serial device.

By using DirectCommunication Xtra, Director, Authorware and Shockwave applications can:

  • Query for available serial and parallel ports on the system

  • Establish a connection with external devices

  • Send and receive text or binary data to/from connected devices

  • Get and set the baud rate, data bits, stop bits, parity, buffer size, time-outs and flow control communication settings

  • Direct connected devices to perform extended functionality and control the port signals

  • Communicate with multiple devices simultaneously

The Xtra is Shockwave safe, so it can also be used with Shockwave 7 and above and when Director safety features are turned on.
When the Xtra is in safe mode it can communicate with external devices after receiving an authorization from the user.

An auto downloadable Shockwave safe package of the Xtra is also available. It is a compressed, small sized (less than 40K) version of the Xtra that can be downloaded automatically from a web site to the user's local machine whenever needed, and once installed provides Shockwave applications on the web with the ability to communicate with external devices.

DirectCommunication Xtra is available for Director 5 and above, Authorware 4 and above, and is compatible with Windows 9X and newer (including 2000, ME, NT, XP) as well as MacOS 8, 9 and X.

Although newer Macintosh computers do not include built-in external serial ports, applications can use the Xtra to communicate with serial devices that are connected through a USB serial adapter such as the one available from Keyspan - http://www.keyspan.com

 

Installation

Registration

Using DirectCommunication Xtra

Backward Compatibility Notes

Functions Reference

New()
Forget()
commGetDevices()
commConnect()
commDisconnect()
commWrite()
commRead()
commCountCharsInQueue()
commGetBaudRate()
commSetBaudRate()
commGetDataBits()
commSetDataBits()
commGetStopBits()
commSetStopBits()
commGetParity()
commSetParity()
commGetQueueSize()
commSetQueueSize()
commGetTimeOut()
commSetTimeOut()
commGetFlowControl()
commSetFlowControl()
commFlush()
commEscape()
commGetState()

Known Issues

Error Codes

History

 

Installation

DirectCommunication Xtra has an authoring version, a run time version and an auto downloadable Shockwave safe package. The trial version only includes the authoring version.

The authoring version is used by the Director and/or Authorware authoring environment while developing your movie/presentation. It should be placed in your Director and/or Authorware "Xtras" folder.

The run time version is used when running your movie/presentation as a stand-alone application. It should be placed in a folder named "Xtras" that is inside the folder that contains the host projector/package. Alternatively, the run time version can be bundled in projectors/packages (in a similar way you bundle other Director\Authorware files).

When creating Director projectors please note that if the Xtra is listed in the Modify->Movie->Xtras dialog then the "Include in Projector" checkbox must be unchecked otherwise Director will bundle the Authoring version of the Xtra in the projector, which will not work outside the authoring environment. Instead, add the run time version of the Xtra in the "Create Projector" dialog or include it in the projector "Xtras" folder.

The run time version is also used with the Authorware web player and can be bundled in the web package. When creating packages in Authorware, please note that by default, Authorware will attempt to bundle the authoring version of the Xtra. You'd have to modify the application "Publish Settings" in order to instruct Authorware to bundle the run time version instead of the authoring version.

The auto downloadable Shockwave safe package is used by Shockwave for Director. The package should be uploaded to your server from which it will automatically get downloaded and installed by your Shockwave movie, if needed.

The auto downloadable Shockwave safe package consists of the following files:

"DirectComm.w32" - Shockwave safe package for Windows
"DirectComm.ppc" - Shockwave safe package for MacOS 8.x and 9.x
"DirectComm.carb" - Shockwave safe package for MacOS X

Please note that Director requires that all the above files are uploaded to your server even if you're only using the Xtra on one platform.

Once you have decided the location on your server where the auto downloadable packages will be placed, you should modify the "xtrainfo.txt" file in the Director 7 or above folder accordingly. For example, if you upload the downloadable package to "http://www.myserver.com/packs" you should add the following line to "xtrainfo.txt".

[#namePPC:"DirectComm", #nameW32:"DirectComm.x32", #package:"http://www.myserver.com/packs/DirectComm"]

Note that the above entry should consist of a single line in the "xtrainfo.txt" file.

Finally, add a reference to the auto downloadable package in your movie. Open a movie that uses the DirectCommunication Xtra. From the Modify->Movie->Xtras dialog in Director, select the "DirectComm" Xtra in the list of Xtras. The "Download if Needed" check box should now be enabled. (If it's not enabled, make sure the filename in "xtrainfo.txt" matches the actual filename of the Xtra). Click on the check box and Director will load information from the package file for each platform and add it to the current movie.

IMPORTANT: The authoring, run time and Shockwave versions can not coexist in the same "Xtras" folder, so be sure to place the appropriate version in the appropriate folder.

You can freely distribute the run time version and Shockwave safe package of DirectCommunication Xtra with any application developed by you, and you alone. You can not redistribute the authoring version. Please refer to the license agreement for further information.

 

Registration

DirectCommunication Xtra is a commercial product. 

Basically, there are 3 types of licenses: Single, Site and Corporate.

Single License: Entitles an organization to receive one copy of the licensed Xtra(s) which can only be used by a single developer on a single computer at any one time.

Site License: Entitles an organization to receive one copy of the licensed Xtra(s) which can be used by any number of developers on any number of workstations within one site.

Corporate License: Entitles an organization to receive one copy of the licensed Xtra(s) which can be used by any number of developers on any number of workstations within the entire corporation (multiple sites).

Once you have licensed DirectCommunication Xtra, you will be given a serial number. Your DirectCommunication Xtra serial number should be passed to the New() function when creating the DirectCommunication Xtra instance in order to unlock the trial limitations. Once the Xtra is unlocked, trial warnings will no longer be presented, there will be no other limitations and the run-time and Shockwave versions of the Xtra will become activated.

Be sure to protect the call to New() so that your DirectCommunication Xtra serial number would not become exposed to others. This can be done in a similar way you protect the rest of your application source code. If you intend to distribute your application with open source code then pass New() the number 0 as your serial number. This will switch the Xtra into a trial mode and you can instruct developers to change the number 0 with their serial number. Alternatively, you can protect just the appropriate New() calls in your code.

The New() function should be called before any of the other Xtra functions are called.

You can freely distribute the run time version and Shockwave safe package of DirectCommunication with any application developed by you, and you alone. You can not redistribute the authoring version. Please refer to the license agreement for further information.

Note that if your application needs to run on both Windows and MacOS, you'd need to obtain a license for both the Windows and MacOS versions of the Xtra.
 

 

Using DirectCommunication Xtra

 

Following are step by step instructions on how applications can use the Xtra to communicate with devices connected to the serial or parallel ports.

Step 1 - Create a new instance of DirectCommunication Xtra and store it for a later use.

The DirectCommunication instance is a reference to a serial or parallel device. Applications have to store it in a variable so that they can later on pass it as the first parameter to the other Xtra functions. In essence, it informs the Xtra functions which device the request is referring to.

Lingo Sample Code for Director :

Set Device = new (Xtra "DirectCommunication", 0)

Sample Code for Authorware :

Device := NewObject ("DirectCommunication", 0)

JavaScript Sample Code for Director :
var Device = new xtra ("DirectCommunication", 0)

Step 2 - Query for all available serial and parallel ports on the system.

Lingo Sample Code for Director :

set Devices = commGetDevices(Device)
put Devices

Sample Code for Authorware :
Devices := CallObject (Device, "commGetDevices")
trace (Devices)

JavaScript Sample Code for Director :

var Devices = Device.commGetDevices()
trace (Devices)

Devices variable now includes a list of strings indicating the names of all serial and parallel ports available on the system, i.e. ["COM1","COM2","COM3","COM4","LPT1"]. The sample code above displays the Devices variable in the message window.

Step 3 - Establish a connection with the device.

The following example attempts to connect to the first port in the Devices list. It assumes that at least one serial or parallel port is available on the system (i.e. the Devices list obtained in the previous step is not empty). If the device you're trying to communicate with is not connected to the first port, change 1 with the number of port on which the device is connected to. Note that the connection will fail if the specified port is being used by other applications.

Lingo Sample Code for Director :

set Error = commConnect (Device, GetAt(Devices, 1))
if (Error) then
    put "Can't connect to the device, error # "&Error
else
    put "A connection was established successfully." 
end if

Sample Code for Authorware :

Error := CallObject (Device, "commConnect", Devices[1])
if (Error) then
    trace ("Can't connect to the device, error # "^Error)
else
    trace ("A connection was established successfully.")
end if

JavaScript Sample Code for Director :

var Error = Device.commConnect ( Devices.GetAt(1))
if (Error)
{
trace( "Can't connect to the device, error # "+Error)
abort()
}
else
{
trace( "A connection was established successfully." )
}

By default, commConnect() initializes the port setting on all platforms to 9600 bps baud rate, 8 data bits, 1 stop bit, no parity, no flow control, 4096 bytes input and output buffers and 3 seconds writing time-out. These settings can be changed after the connection is made to ensure proper communication with the device.

Step 4 - Set the port operational settings.

Applications can use the commSetBaudRate(), commSetDataBits(), commSetStopBits(), commSetParity(), commSetFlowControl(), commSetTimeOut() and commSetQueueSize() functions to set the baud rate, data bits, stop bits, parity, flow control, writing time-out and queue size settings in which the port operates. For example, lets say that the device that is connected to the port operates at 57600 bps baud rate. This rate does not match the 9600 bps in which the port is configured to by default. commSetBaudRate() can be used to set the port baud rate to 57600 bps as follows:

Lingo Sample Code for Director :

set Error = commSetBaudRate (Device, 57600)
if (Error) then
    put "Can't set the baud rate, error # "&Error
else
    put "The baud rate was set successfully." 
end if

Sample Code for Authorware :

Error := CallObject (Device, "commSetBaudRate", 57600)
if (Error) then
    trace ("Can't set the baud rate, error # "^Error)
else
    trace ("The baud rate was set successfully.")
end if

JavaScript Sample Code for Director :

var Error = Device.commSetBaudRate (57600)

if (Error)
{trace( "Can't set the baud rate, error # "+Error)}

else
{trace("The baud rate was set successfully." )}

Step 5 - Send data to the device.

After the port is configured applications can use commWrite() to send data to the connected device.

The following sample sends to the port the string "AT" following by the RETURN character. If a modem is connected to the port and is working properly, it will reply with an "OK" message:

Director example -

set NumOfCharsSent = commWrite (Device, "AT"&RETURN)
put NumOfCharsSent & " characters were successfully sent to the device."

Authorware example -

NumOfCharsSent := CallObject (Device, "commWrite", "AT"^RETURN)
trace (NumOfCharsSent^" characters were successfully sent to the device.")

JavaScript Sample Code for Director :

var NumOfCharsSent = Device.commWrite("AT\n")
trace( NumOfCharsSent + " characters were successfully sent to the device.")
 

Note that commWrite() may time out and return without sending data to the device, or after sending part of the data, in which case applications should call it again to send the remaining data. More details on this issue as well as additional important information on commWrite() can be found in the function documentation.

Step 6 - Read data sent from the device.

Data sent from the connected device is stored in the port input buffer. commRead() can be used to retrieve the data that resides in the port input buffer. When expecting data to be sent from the device, applications should frequently read from the port until all the data is received. Note that the data may be received in parts and therefore commRead() result should be appended to what has been received from previous calls until the complete data is received.

The following example retrieve the data sent from the device and displays it in the message window:

Lingo Sample Code for Director :

put commRead (Device)

Sample Code for Authorware :

trace (CallObject (Device, "commRead"))

JavaScript Sample Code for Director :

trace( Device.commRead () )

Step 7 - Disconnect from the device.

As soon as the communication with the device is over, disconnect from the port to allow other applications to use it:

Lingo Sample Code for Director :

commDisconnect (Device)

Sample Code for Authorware :

trace (CallObject (Device, "commDisconnect"))

To communicate with another device, jump back to step # 3, otherwise, delete the DirectCommunication Xtra instance which was created in the first step.

JavaScript Sample Code for Director :

Device.commDisconnect ()

Step 8 - Delete the DirectCommunication Xtra instance.

Lingo Sample Code for Director :

set Device = 0

Sample Code for Authorware :

DeleteObject(Device)

JavaScript Sample Code for Director :

var Device = 0

Backward Compatibility Notes

 

DirectCommunication Xtra version 2.0 is not backward compatible with version 1.x.

A summarize of changes and new features can be found in the History section of this documentation. It describes in details how to update code that was written to utilize DirectCommunication Xtra version 1.x to use the new version.

 

Functions Reference

Director: New ( Xtra "DirectCommunication", integer SerialNumber )

Authorware: NewObject ("DirectCommunication", integer SerialNumber )

Creates a new DirectCommunication Xtra instance.

The DirectCommunication instance is a reference to a serial or parallel device. Applications have to store it in a variable so that they can later on pass it as the first parameter to the other Xtra functions. In essence, it informs the Xtra functions which device the request is referring to.

Parameter :

SerialNumber : DirectCommunication Xtra Serial Number. If you are using the trial version, pass the number 0.

Returns : A new instance of DirectCommunication Xtra.

Remarks :

A newly created instance is not connected to any device. After creating the instance applications can use the commGetDevices() function to obtain a list of all available serial and parallel ports on the system. Applications can then call commConnect() to establish a connection with one of the available ports in order to communicate with the device that is attached to it.

Each DirectCommunication instance can reference a single device at a time. In order to communicate with multiple devices at the same time, create multiple instances of DirectCommunication Xtra and work with them simultaneously.

 

Director: Forget ( object me )

Authorware: DeleteObject ( object me )

Deletes a DirectCommunication Xtra instance.

Parameter :

object me : DirectCommunication Instance.

Returns : None.

Remarks :

In Director, you can also delete the DirectCommunication Xtra instance by setting it to zero.

If the instance is connected to a serial or parallel port by the time it is deleted, the Xtra will gracefully disconnect it from the port.

 

commGetDevices ( object me )

Returns a list containing the names of all serial and parallel ports available on the system.

Parameter :

object me : DirectCommunication Instance.

Returns : A list containing the names of all serial and parallel ports available on the system. If the function fails or if there are no serial and parallel ports on the system, the returned value is an empty list.

Remarks :

To establish a connection with a particular device, applications can call commConnect() and pass it the name of the port on which the device is connected to, as it is returned by this function.

Some or all of the ports returned by this function may be in use by other applications or may be unavailable for connections. As a result, applications may not be able to connect to them (commConnect() will fail).

On Windows, built-in serial ports are typically named "COMx", where x is the port number, i.e. "COM1" refers to the first serial port. Similarly, built-in parallel ports are typically named "LPTx", where x is the port number, i.e. "LPT1" refers to the first parallel port.
On MacOS classic, the returned list typically includes the standard built-in modem and printer ports as well as any other compatible port that is registered with the Communications Resource Manager, such as the one added by the Keyspan USB serial adapter.
On MacOS X, the returned list typically includes the built-in port in which the built-in modem is connected to, if one is available, following by all ports added to the system via USB serial adapters.

 

commConnect ( object me, string DeviceName )

Establishes a connection with the device that is connected to the specified serial or parallel port.

The function also initializes the connection settings as follows:

Baud rate = 9,600 bits per second
Data bits = 8
Stop bits = 1
Parity = None
Flow control = None
Input buffer = 4096 bytes
Output buffer = 4096 bytes (if available)
Write time-out = 3 seconds

Parameters :

object me : DirectCommunication Instance.

DeviceName : The name of the serial or parallel port to connect to. Use commGetDevices() to obtain a list containing the names of all serial and parallel ports available on the system. On MacOS X you can alternatively set this parameter to a case sensitive pathname pointing to the device file. On Windows, COM10 and above should be specified as "\\.\COMXX" where XX is the COM number, i.e. "\\.\COM10" for COM10.

Returns : 0 (zero) if the function was successful or an error code otherwise.

Remarks :

A serial port is a non-sharable resource. If your application has the port open, no other application can open it. For this reason, you should always connect and disconnect serial devices on demand. For example, if your application only uses the serial device as part of its registration process, you should connect to it when you commence the registration and disconnect it immediately after you are done.

If the DirectCommunication instance is already connected to a serial or parallel port by the time this function is called, the function will first disconnect it from the port. If the function then fails to connect to the specified port, the instance would be left unconnected.

Safe mode note:

The Xtra is always in safe mode when it is used by a Shockwave movie that is running from within a web browser. A safe mode can also be set in the Director authoring environment or projectors by setting the safePlayer lingo property to true before creating the DirectCommunication instance.

When the Xtra is in safe mode, this function will display a dialog box asking the user to authorize the connection with the specified device. The function will fail if the user does not authorize the connection. This is the only security warning that appears in a safe mode.

 

commDisconnect ( object me )

Disconnects the DirectCommunication instance from the device it is currently connected to.

Parameter :

object me : DirectCommunication Instance.

Returns : 0 (zero) if the function was successful or an error code otherwise.

 

commWrite ( object me, any Data )

Writes the specified data to the connected device.

Parameters :

object me : DirectCommunication Instance.

Data : The data to write to the port.

This parameter may be a number or a string. If it is a string, the Xtra will send the specified string to the device. If it is a number, it can be in the range of 0-255, and the equivalent ASCII character \ HEX value \ bits will be sent to the device, for example, passing 65 will send the ASCII character "A", which is equivalent to the HEX value 41, which is equivalent to the bits 01000001. Passing 0 will send a NULL character.

Returns : The number of characters that were successfully written to the port, or 0 (zero) if no characters were written to the port as a result of an error.

Remarks :

This function is synchronous, meaning that it will not return control to your application until it completes sending all the specified data to the device or alternatively to the port output buffer, if one is available (The output buffer stores characters that were sent to the port using this function but which were not yet transmitted to the device) or until a time-out occurs, whichever comes first.

If the port is utilizing an output buffer, and the output buffer has sufficient space to store the specified data, the data will be sent to the output buffer and the function will return immediately. If the output buffer is full, the function will pause transmission until some free space becomes available and it will then continue to send the remaining data. It will keep doing so until all the specified data is sent or a time-out occurs. If the output buffer is not available, the function will send the specified data directly to the device and will return when it completes sending all the data to the device or when a time-out occurs. Output buffers are supported on Windows and MacOS X, though the built-in serial driver on Windows does not currently utilize the output buffer.

Applications can use the commSetTimeOut() function to specify a time-out for this function. The default is 3 seconds. A time out usually occurs when the device is holding off transfers through hardware or software handshaking. In such cases, if the output buffer is full or if it is not available, the function fails to write the data and times out. A time out may also occur when the baud rate is not high enough to send all the specified Data within the specified time frame.

Note though that the time-out feature is not available on MacOS classic. It is only available on Windows and MacOS X. When your application is running under MacOS classic it should check whether output is suspended by handshaking prior to calling this function, otherwise the function will not return control to your application until the output is resumed. For example, if the flow control is RTS/CTS, it should refrain from sending data until the CTS and DSR signals are on. These signals can be queried using commGetState().

It is possible that the function may not write all the specified data to the device, for example, as a result of the output port buffer being full or because a time out has occurred. For this reason, applications must check the returned value to get the number of characters that were successfully written to the port. If the returned value is not equal to the number of characters specified in Data, applications should call this function again to write the remaining data.

If the input buffer of the receiving device is full, and the output buffer of the port is full or unavailable, and there is no flow control setting, additional data sent to the device using this function may get lost.

In Director, if Data is set to a string that includes NULL characters (characters whose ASCII value is zero), all characters including the NULL characters will be sent to the device. Note that string variables in Director may include NULL characters, though if you try to display them on the screen in a typical manner only the characters up to the first NULL will appear. In example:

MyData = "12"&NumToChar(0)&"3"
put MyData
-- "12"
put the length of MyData
-- 4

If you now pass MyData variable as the Data parameter to this function the Xtra will send all the 4 characters to the port.

In Authorware, if Data is set to a string that includes NULL characters, all characters up to the first NULL character will be sent to the device. To send a NULL character from Authorware, set Data to the number zero.

To send an HEX value, set Data to the equivalent ASCII character or number. For example, HEX value 6E is equivalent to ASCII character number 110, which is the letter "n". To send 6E to the port, set Data to the number 110 or to the letter "n". To send multiple HEX values, either call this function multiple times, once for each HEX value, or set Data to a string that includes all the HEX values. For example, the string "np=" is equivalent to the HEX values "6E 70 3D".

A freeware ASCII table can be downloaded from our web site for your convenience.

 

commRead ( object me )

Reads data from the opened device.

Parameter :

object me : DirectCommunication Instance.

Returns : A string containing the data read from the device or an empty string if an error has occurred or if the input port buffer is empty. See the remarks section for a special case under Authorware.

Some devices send out hex or decimal values. This function will return the equivalent ASCII string representation of these values. For example, a decimal value of 65 is equivalent to the HEX value 41 and has a string representation of the ASCII character "A". If the connected device sends 65 decimal \ 41 HEX, this function will return "A". In Director, you can use the CharToNum() lingo function to obtain the decimal value corresponds of each of the returned characters. In Authorware, a similar function is called Code(). In this example, CharToNum() / Code() functions will return 65 if the returned "A" character is passed to them. Multiple decimal/hex values are represented as a string with multiple characters. For example, if this function returns "ABC" that means that the device sent decimal values 65, 66 and 67, which are equivalent to the hex values 41, 42 and 43, respectively. Note that the visual representation of the returned string may appear as garbage since some hex/decimal values may be associated with characters that can not be displayed or have no visual representation at all, though you can still use CharToNum() / Code() to obtain the decimal values of the returned characters, and if necessary translate them to HEX.

A freeware ASCII table can be downloaded from our web site for your convenience.

Remarks :

When a device sends out data to your application, the data is stored in the port input buffer until it is retrieved by your application. The function reads all the characters that are available in the port input buffer by the time it is called and frees up space for additional incoming data. If the port input buffer is empty, the function will return an empty string without attempting to read from the port.

Applications can use commSetQueueSize() to set the capacity of the port input buffer. If the input buffer of the port is full, and the output buffer of the sender device is full or unavailable, and there is no flow control setting, additional data sent to the application may get lost.

In Director, if the data read from the device includes NULL characters (characters whose ASCII value is zero), all characters including the NULL characters will be returned. Note though that if you try to display the returned string in a typical manner, only the characters up to the first NULL will appear. You can use string manipulation lingo functions to properly parse the returned data.

In Authorware, if the data read from the device includes NULL characters, the result would be a list of strings instead of a single string, where the NULL characters are represented as an empty string item in the list. For example, if the returned data is the string "123" following by a NULL character following by the string "456", the function result would be ["123", "", "456"]. Authorware applications that expect to receive data with NULL characters must check the type of the returned value using the TypeOf command. If it is #string, the data read from the device does not include NULL characters and the returned value is a string containing the retrieved data. Otherwise, if the type of the returned value is #linearList, the data read from the device includes NULL characters and the returned value is a list of strings containing the retrieved data.

 

commCountCharsInQueue ( object me, integer Queue )

Obtains the number of characters in the port input and output buffers.

Parameters :

object me : DirectCommunication Instance.

Queue : A number specifying the buffer to check. Pass 0 to obtain the number of characters in the port input buffer and 1 to obtain the number of characters in the port output buffer.

Returns : The number of characters in the specified port buffer.

Remarks :

The port input buffer stores characters received from the device but which were not yet read using commRead(). The port output buffer stores characters that were sent to the port using commWrite() but which were not yet transmitted to the connected device. This function can be used to query for the number of characters that currently reside in the specified port buffer. For additional information on input and output buffers, please refer to the commWrite(), commRead(), commGetQueueSize() and commSetQueueSize() remarks.

 

commGetBaudRate ( object me )

Retrieves the current baud rate at which the serial port operates.

Parameter :

object me : DirectCommunication Instance.

Returns : The current baud rate or zero if an error has occurred.

 

commSetBaudRate ( object me, integer BaudRate )

Sets the baud rate at which the serial port operates.

Parameters :

object me : DirectCommunication Instance.

BaudRate : An integer specifying the baud rate in bits per second. Common baud rate values are 150, 300, 600, 1200, 1800, 2400, 3600, 4800, 7200, 9600, 14400, 19200, 28800, 38400, 57600, 115200 and 230400.

Returns : 0 (zero) if the function was successful or an error code otherwise.

Remarks :

When setting the baud rate to a non standard rate, the function may succeed but the actual baud rate may be slightly different than the one requested. Upon success of this function applications can call commGetBaudRate() to obtain the actual baud rate.

 

commGetDataBits ( object me )

Retrieves the current number of bits in the bytes transmitted and received to/from the connected device.

Parameter :

object me : DirectCommunication Instance.

Returns : The current number of bits in the bytes transmitted and received. Possible values are 5, 6, 7 and 8.

 

commSetDataBits ( object me, integer DataBits )

Sets the number of bits in the bytes transmitted and received to/from the connected device.

Parameters :

object me : DirectCommunication Instance.

BaudRate : An integer specifying the number of bits in the bytes transmitted and received. Possible values are 5, 6, 7 and 8.

Returns : 0 (zero) if the function was successful or an error code otherwise.

 

commGetStopBits ( object me )

Retrieves the current number of stop bits used while communicating with the connected device.

Parameter :

object me : DirectCommunication Instance.

Returns : The current number of stop bits. Common values are 1 for 1 stop bit, 2 for 2 stop bits and 15 for 1.5 stop bits.

 

commSetStopBits ( object me, integer StopBits )

Sets the number of stop bits to be used in communicating with the connected device.

Parameters :

object me : DirectCommunication Instance.

StopBits : An integer specifying the number of stop bits. Common values are 1 for 1 stop bit, 2 for 2 stop bits and 15 for 1.5 stop bits. 1.5 stop bits is not supported on MacOS X.

Returns : 0 (zero) if the function was successful or an error code otherwise.

 

commGetParity ( object me )

Retrieves the current parity scheme used while communicating with the connected device.

Parameter :

object me : DirectCommunication Instance.

Returns : The current parity scheme. Possible values:

0 - No parity.
1 - Odd.
2 - Even.
3 - Mark (Windows only).
4 - Space (Windows only).

 

commSetParity ( object me, integer Parity )

Sets the parity scheme to be used in communicating with the connected device.

Parameters :

object me : DirectCommunication Instance.

Parity : An integer specifying the parity scheme. Possible values:

0 - No parity.
1 - Odd.
2 - Even.
3 - Mark (Windows only).
4 - Space (Windows only).

Returns : 0 (zero) if the function was successful or an error code otherwise.

 

commGetQueueSize ( object me, integer Queue )

Retrieves the current size of the port input and output buffers.

Parameters :

object me : DirectCommunication Instance.

Queue : A number specifying the buffer to query. Pass 0 to obtain the size of the port input buffer and 1 to obtain the size of the port output buffer.

Returns : An integer indicating the size of the port internal input or output buffer, in bytes. A value of zero indicates that the specified buffer is not in use or can not be retrieved.

Remarks :

The port input buffer stores characters received from the device but which were not yet read using commRead(). The port output buffer stores characters that were sent to the port using commWrite() but which were not yet transmitted to the connected device. This function can be used to check the maximum capacity of the port buffers.

Output buffers are supported on Windows and MacOS X, though the built-in serial driver on Windows does not currently utilize the output buffer. This function is not available on MacOS X. Applications can not query or change the internal input and output buffers under MacOS X.

 For additional information on input and output buffers, please refer to the commWrite() and commRead() remarks.

 

commSetQueueSize ( object me, integer InputQueueSize, OutputQueueSize )

Sets the size of the port input and output buffers.

Parameters :

object me : DirectCommunication Instance.

InputQueueSize : An integer specifying the recommended size of the port internal input buffer, in bytes.

OutputQueueSize : An integer specifying the recommended size of the port internal output buffer, in bytes.

Returns : 0 (zero) if the function was successful or an error code otherwise.

Remarks :

The port input buffer stores characters received from the device but which were not yet read using commRead(). The port output buffer stores characters that were sent to the port using commWrite() but which were not yet transmitted to the connected device. This function can be used to set the maximum capacity of the port buffers.

After calling the commConnect() function to connect to a communications device, but before performing any I/O operations with the device, applications can call this function to set the size of the port internal input and output buffers. By default, commConnect() sets the size of the port input and output buffers to 4096 bytes.

The InputQueueSize and OutputQueueSize parameters specify the recommended sizes for the internal buffers used by the driver for the specified device. For example, YMODEM protocol packets are slightly larger than 1024 bytes. Therefore, a recommended buffer size might be 1200 bytes for YMODEM communications.

Under Windows, the device driver receives the recommended buffer sizes, but is free to use any input and output (I/O) buffering scheme, as long as it provides reasonable performance and data is not lost due to overrun (except under extreme circumstances). For example, the function can succeed even though the driver does not allocate a buffer, as long as some other portion of the system provides equivalent functionality.

Under MacOS classic, setting the InputQueueSize to zero will set the Xtra to use the default built-in port input buffer which is 64 bytes in size.

Output buffers are supported on Windows and MacOS X, though the built-in serial driver on Windows does not currently utilize the output buffer. This function is not available on MacOS X. Applications can not query or change the internal input and output buffers under MacOS X.

For additional information on input and output buffers, please refer to the commWrite() and commRead() remarks.

 

commGetTimeOut ( object me )

Retrieves the time-out for all write operations on the connected device performed by commWrite().

Parameter :

object me : DirectCommunication Instance.

Returns : An integer indicating the total time-out period for write operations, in milliseconds. A value of zero indicates that time-out is not used for write operations.

Remarks :

The time-out feature is not available on MacOS classic and therefore this function will always return 0 under MacOS classic. For additional information on time-outs, please refer to commWrite() remarks.

 

commSetTimeOut ( object me, integer TimeOut )

Sets the time-out for all write operations on the connected device performed by commWrite().

Parameters :

object me : DirectCommunication Instance.

TimeOut : An integer specifying the total time-out period for write operations, in milliseconds. A value of zero indicates that time-out is not used for write operations.

Returns : 0 (zero) if the function was successful or an error code otherwise.

Remarks :

The time-out feature is not available on MacOS classic and therefore this function will fail under MacOS classic.

For additional information on time-outs, please refer to commWrite() remarks.

 

commGetFlowControl ( object me )

Obtains the current flow control setting with the connected device.

Parameter :

object me : DirectCommunication Instance.

Returns : An integer indicating the current flow control setting. For possible values refer to commSetFlowControl().

 

commSetFlowControl ( object me, integer FlowControl )

Sets the flow control setting with the connected device.

Parameters :

object me : DirectCommunication Instance.

FlowControl : An integer specifying the flow control setting. Can be one of the following values:

0 - No flow control (default).

1 - CTS/RTS hardware protocol. Using this protocol by both sides of the connection ensures that data is transferred when both devices are ready and it also prevents a data loss as a result of buffers overflow.

  • The CTS (clear-to-send) signal is monitored for output flow control.
  • The DSR (data-set-ready) signal is monitored for output flow control.
  • Enables the DTR line when the device is opened and leaves it on.
  • Enables RTS handshaking. The driver raises the RTS line when the "type-ahead" (input) buffer is less than one-half full and lowers the RTS line when the buffer is more than three-quarters full. If handshaking is enabled, it is an error for the application to adjust the line by using the commEscape() function.

2 - XON/XOFF protocol. Using this protocol by both sides of the connection ensures that data is transferred when both devices are ready and it also prevents a data loss as a result of buffers overflow.

  • Transmission stops when the XOFF character (defined as ASCII character # 19) is received and starts again when the XON character (defined as ASCII character # 17) is received.
  • The XOFF character is sent when the input buffer is getting full, and the XON character is sent when the input buffer is getting emptied.

Returns : 0 (zero) if the function was successful or an error code otherwise.

 

commFlush ( object me, integer Queue )

Discards all characters from the port input and output buffers.

Parameter :

object me : DirectCommunication Instance.

Queue : A number specifying the buffer to flush. Pass 0 to flush the port input buffer and 1 to flush the port output buffer.

Returns : 0 (zero) if the function was successful or an error code otherwise.

 

commEscape ( object me, integer Function )

Directs the connected device to perform an extended function.

Parameters :

object me : DirectCommunication Instance.

Function : An integer specifying the extended function to be performed. This can be one of the following values:

1 - Clears the DTR (data-terminal-ready) signal.
2 - Sends the DTR (data-terminal-ready) signal.
3 - Clears the RTS (request-to-send) signal.
4 - Sends the RTS (request-to-send) signal.
5 - Causes transmission to act as if an XON character has been received.
6 - Causes transmission to act as if an XOFF character has been received.
7 - Restores character transmission and places the transmission line in a non break state.
8 - Suspends character transmission and places the transmission line in a break state until this function is called again with the extended function code # 7. Note that this extended function does not flush data that has not been transmitted.

Returns : 0 (zero) if the function was successful or an error code otherwise.

 

commGetState ( object me, integer Signal )

Obtains the current state of the specified signal.

Parameters :

object me : DirectCommunication Instance.

Signal : An integer specifying the signal to check. This can be one of the following values:

1 - Checks the CTS (clear-to-send) signal.
2 - Checks the DSR (data-set-ready) signal.
3 - Checks the ring indicator signal.
4 - Checks the the RLSD (receive-line-signal-detect) signal.

Returns : 1 if the signal specified by the Signal parameter is on or 0 (zero) if it is off or if the function fails.

 

Known Issues


The list returned by commGetDevices() does not include the USB serial adapter

Ensure that the USB serial adapter device driver software is properly installed. The software is distributed with the USB serial adapter and is usually available on the manufacture web site.

On MacOS X, if you use the serial adapter and then try to use it in a classic environment running from within MacOS X you may need to re-attach the adapter to the system.

On Windows, if you just installed the USB serial adapter device driver for the first time you may need to restart the system for the adapter to appear in devices list. However, if you know the name of the port where the adapter is connected you can connect to it using commConnect() without restarting the system.

 

Error Codes

 

Windows and MacOS Errors

13000 - Not enough memory.
13001 - The DirectCommunication instance is not connected. Call commConnect() first.
13002 - The specified port could not be found.
13003 - Can't connect to the port because it is being used by another application.
13004 - Invalid parameter.
13005 - Feature is not supported on this operating system.
13006
- Can't connect to the specified port in a safe mode because the user did not approve the connection.

MacOS X Errors

13100 - IO Kit is not available.
13101 - Dictionary service is not available.
13102
- POSIX is not available.

The DirectCommunication Xtra functions might return additional platform specific error codes that are not listed above.

 

History

 

03/30/2003 - Version 2.0 released.

  • A fully compatible MacOS X version is now available.

  • The Xtra was marked as Shockwave safe. An auto downloadable Shockwave safe package is now available.

  • Added binary support in Authorware.

  • Added support for multiple serial ports on MacOS classic.

  • New() no longer establishes a connection with the device. It simply creates a new instance. As a result, it no longer takes the CommName, InQueue and OutQueue parameters. To establish a connection with a device use commConnect(). To overwrite the default port buffer size use the new commSetQueueSize() and commGetQueueSize() functions. In previous versions, New() may have failed to create an instance if a connection could not be made. This is not applicable anymore and therefore New() will always return a new instance. If a connection could not be made with the device, commConnect() will return the appropriate error code.

  • In pervious versions you had to delete the instance in order to disconnect from the device. In the new version, deleting the instance will disconnect from the device as well, but you can also use commDisconnect() to disconnect from the device while still retaining the instance.

  • commGetDevices() was added to obtain a list of all compatible serial and parallel ports on the system. Applications should use it to locate available ports rather than assuming the names of the ports as was the case with previous versions.

  • commConnect() and commDisconnect() were added to allow applications to connect and disconnect to/from serial/parallel ports without the need to recreate the instance. commConnect() initializes the port setting on all platforms to 9600 bps baud rate, 8 data bits, 1 stop bit, no parity, no flow control, 4096 bytes input and output buffers and 3 seconds writing time-out. These settings can be changed after the connection is made.

  • WriteComm() is now commWrite(). The new function can write both strings and numbers. It was enhanced to support NULL characters in Authorware.

  • Readcomm() is now commRead(). The new function was enhanced to support NULL characters in Authorware..

  • SetCommBaudRate() was renamed to commSetBaudRate(). On MacOS classic, support for 115,200 and 230,400 baud rates was added. The function will now return zero upon success or an error code otherwise.

  • SetCommDataBits() was renamed to commSetDataBits(). The function will now return zero upon success or an error code otherwise.

  • SetCommStopBits() was renamed to commSetStopBits(). The function will now return zero upon success or an error code otherwise. You now have to pass 1 for 1 stop bit and 15 for 1.5 stop bits.

  • SetCommParity() was renamed to commSetParity(). The function will now return zero upon success or an error code otherwise.

  • FlushComm() was renamed to commFlush(). It is now available on MacOS as well and can flush the port input and output buffers separately.

  • SetCommFlowControl() was renamed to commSetFlowControl(). All 3 flow control options now have a similar behavior across Windows, MacOS classic and MacOS X. The function will now return zero upon success or an error code otherwise.

  • SetCommTimeOut() was renamed to commSetTimeOut(). The function will now return zero upon success or an error code otherwise.

  • EscapeComm() was renamed to commEscape(). All the extended functions are now available on all platforms (Windows, MacOS classic and MacOS X). The function will now return zero upon success or an error code otherwise.

  • The following functions were renamed but their functionality was not changed:
    GetCommBaudRate() -> commGetBaudRate()
    GetCommDataBits -> commGetDataBits()
    GetCommStopBits() -> commGetStopBits()
    GetCommParity() -> commGetParity()

  • The following functions were added:

    commCountCharsInQueue()
    commGetQueueSize()
    commSetQueueSize()
    commGetTimeOut()
    commGetFlowControl()
    commGetState()

  • Added extensive documentation and sample code for both Director and Authorware.

  • Various minor improvements and bug fixes.

10/08/2000 - Version 1.1.2 released.

  • The Xtra was updated to be fully compatible with future versions of Director.

02/09/1999 - Version 1.1.1 released.

  • Fixed a problem with WriteComm() under Authorware, Windows 98.

07/29/1998 - Version 1.1 released.

  • Compatible MacOS version is now available.
  • GetCommError() revised and documented.
  • New methods: EscapeComm() and SetCommTimeOut().
  • All methods now return nonzero if succeeded and zero if failed (instead of void).
  • WriteComm() result is the number of bytes actually written.

06/05/1998 - Version 1.0.1 released.

  • There was a bug in version 1.0 that caused WriteComm() and ReadComm() methods to ignore all characters located after the first NULL character (NumToChar(0)), if exist, in a string. This bug was fixed. You can now read from and write to a communication port strings that contain NULL characters.

09/24/1997 - Version 1.0 released.



DirectXtras Inc.
P.O Box 2645, Menlo Park, CA, 94026, U.S.A
Voice: +1-415-5058249, Fax: +1-801-8585841
Toll Free: 1-800-4453093
E-mail General Information: info@directxtras.com
E-mail Technical Support: support@directxtras.com

Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.
WebMaster: tamar@directxtras.com
Last Updated: 9/18/2004 8:36:53 AM.