ftp.nice.ch/pub/next/developer/resources/libraries/LGDCommunicationKit.1.0.N.a.tar.gz#/LGDCommunicationKit-1.0/Documentation/LGDSerialPort.rtf

This is LGDSerialPort.rtf in view mode; [Download] [Up]

Library Documentation, Copyright © 1993 Looking Glass Design, Inc.
LGDCommunicationKit Release 1.0 (prerelease)
Project Manager:  Paul Girone
Written by: Mike Gobbi, June 22/1993 (5:09 pm)
$Revision: 1.3 $




LGDSerialPort





Inherits From:	Object 

Conforms To:	LGDBasicPortProtocol 

Declared In:	LGDSerialPort.h





Class Description

The LGDSerialPort provides a convenient way to access the serial ports through NeXTStep.  This object does not depend on the AppKit, and may be used in programs which do not have a GUI or an instance of the Application object.

Basic Operations

For most uses of the serial port, all that will be necessary to do will be to open it, read and write to it, and then close it.  The eight methods commonly used are
	- openAndLockDevice:mode:timeout:
	- unlockAndClose
	- sendString:
	- getString:max:
	- sendBlock:size:all:
	- getBlock:size:all:
	- status
	- statusString

Example:
{
	id port = [[LGDSerialPort alloc] init];
	char buffer[20];
	
	if ([port openAndLockDevice:"cufa"
		mode:LGD_SP_COOKED] timout:1) {
	
		[port sendString:"atdt123-4567"];
		
		while (0>=[port getString:buffer max:20]) {
			if (!strcmp(buffer, "login:"))
				break;
			else
				[port sendString:""];
		}
		
		[port sendString:"myUsername"];
		
		while (0==[port getString:buffer max:20]);
		[port sendString:"myPassword"];
		
		...
		
		[port sendString:"exit"];
	}
	
	if ([port status]) {
		NXRunAlertPanel("Port error", "%s", 
			NULL, NULL, NULL, 
			[port statusString]);
	}
	
	[port unlockAndClose];
	[port free];
}

Serial Devices

Unix has several standard serial devices, all of which eventually pass through one of two serial ports (ports A and B).  Even if a device is free, it may be unable to be opened because another device is using the serial port.  The standard serial devices in the NeXTstep environment are summarized below:

	ttya	ttyb	Used for incoming connections from directly connected terminals without flow control.
	ttyfa	ttyfb	Used for incoming connections from directly connected terminals with flow control.
	ttyda	ttydb	Used for incoming connections from modems.
	ttydfa	ttydfb	Used by systems whose hardware supports RTS/CTS flow control (68040 and later) for incoming connections from modems.
	cua	cub	Used for outgoing connections to modems.
	cufa	cufb	Used by systems whose hardware supports RTS/CTS flow control (68040 and later) for outgoing connections to modems.

Common misunderstandings

It is important to realize that all port settings must be understood from the perspective of the entity sending data in through the port.  In particular, setting full duplex (echo) mode will often cause a feedback loop as you send a character, the modem automatically echos it, the device echos it back to the modem, which echos it, ad infinitum.

The word flush has a slightly different meaning with serial ports than with display devices.  To flush a window server is to block until the server has finished executing all the instructions in its queue, but to flush a serial device is to discard all the information in the queue.  The end result (an empty queue) is the same, but the mechanism is quite different.

Permissions

The serial devices are generally protected against unauthorized write operations.  In order for your application to use these devices, it will be necessary to have write permission added to the devices, or to set up the application to run as setuid (usually user uucp group wheel).  Both of these tasks will have to be performed by the system administrator.  See IntroLGDCommunicationKit.rtf for a further discussion of file permissions.




Instance Variables

int status;
NXAtom device;
int descriptor;
int discipline;
struct sgttyb sgttyb;
struct tchars tchars;
unsigned short lmode;
struct ltchars ltchars;
struct winsize winsize;
struct __spFlags1 {
	unsigned autoSet:1;
	unsigned autoGet:1;
} spFlags1;
struct __spFlags2 {
	unsigned locked:1;
	unsigned open:1;
} spFlags2;




status	Current error status.
device	Current device.
descriptor	File descriptor for current device (if open).
discipline	Unix flag.
sgttyb	Unix flags.
tchars	Unix flags.
lmode	Unix flags.
ltchars	Unix flags.
winsize	Unix flags.
spFlags1.autoSet	Whether to change port settings whenever a set¼ method is invoked.
spFlags1.autoGet	Whether to query port settings whenever a get¼ method is invoked.
spFlags2.locked	Whether the current device is locked.
spFlags2.open	Whether the current device is open.






Adopted Protocols

LGDBasicPortProtocol 	- baudRate
	- continue
	- CRMassage
	- dataAvailable
	- discipline
	- flushInput
	- flushOutput
	- getBlock:size:all:
	- isDeviceAvailable:
	- isOpen
	- lowerBreak
	- lowerDTR
	- mode
	- openAndLockDevice:mode:timeout:
	- parity
	- pause
	- raiseBreak
	- raiseDTR
	- sendBlock:size:all:
	- setBaudRate:
	- setCRMassage:
	- setDiscipline:
	- setDuplex:
	- setMode:
	- setParity:
	- unlockAndClose








Method Types

Factory methods	- init
	- copyFromZone:
	- free

Device information	+ getLockFile:forDevice:
	+ writeLockFileContents:forDevice:
	+ getDeviceFile:forDevice:

Connecting	- isDeviceAvailable:
	- setDevice:
	- device
	- lock
	- unlock
	- open
	- openWithTimeout:
	- close
	- openAndLockDevice:mode:timeout:
	- unlockAndClose
	- isOpen
	- isLocked
	- _fileDescriptor

Communication	- sendCharacter:
	- sendString:
	- sendString:withTrailer:
	- sendBlock:size:all:
	- getCharacter:
	- getString:max:
	- getString:max:termChars:
	- getBlock:size:all:

Signals	- raiseBreak
	- lowerBreak
	- sendBreak
	- raiseDTR
	- lowerDTR
	- sendDisconnect
	- pause
	- continue

Data buffers	- dataAvailable
	- flushInput
	- flushOutput
	- flush

Error status	- clearStatus
	- status
	- statusString

Modifying states en masse	- applySgttyb:
	- applyTchars:
	- applyLmode:
	- applyLtchars:
	- applyWinsize:
	- fetchSgttyb:
	- fetchTchars:
	- fetchLmode:
	- fetchLtchars:
	- fetchWinsize:
	- applySettings
	- fetchSettings
	- applySettings::::::
	- fetchSettings::::::

Automating state changes	- setAutoSetEnabled:
	- setAutoGetEnabled:
	- autoSetEnabled
	- autoGetEnabled

Modifying states individually	- setDiscipline:
	- setBaudRate:
	- setNumericBaudRate:
	- setParity:
	- setCRMassage:
	- setDuplex:
	- setMode:
	- discipline
	- baudRate
	- numericBaudRate
	- parity
	- CRMassage
	- mode

Archiving	- write:
	- read:






Class Methods

getDeviceFile:forDevice:
+ (const char *)getDeviceFile:(char *)buffer 
forDevice:(const char *)device

Stores the full pathname of device in buffer, which is assumed to have room for at least MAXPATHLEN+1 characters.  Returns buffer.

By default, this method prepends ª/dev/º onto device to get the path, but this method may be overridden by subclasses to provide different behaviour.

See also:  - openWithTimout:, - openAndLockDevice:mode:timeout:




getLockFile:forDevice:
+ (const char *)getLockFile:(char *)buffer forDevice:(const char *)device

Stores the full pathname of the lock file for device in buffer, which is assumed to have room for at least MAXPATHLEN+1 characters.  Returns buffer.

By default, this method prepends ª/usr/spool/uucp/LCK/LCK..º onto device to get the path, but this method may be overridden by subclasses to provide different behaviour.

See also:  - lock, - openAndLockDevice:mode:timeout:




writeLockFileContents:forDevice:
+ (int)writeLockFileContents:(int)fileDescriptor
 forDevice:(const char *)device

Writes the lock file contents to the file identified by fileDescriptor and returns fileDescriptor.

By default, this method prepends writes the process id (in ASCII) into the file and appends a newline, but this method may be overridden by subclasses to provide different behaviour.

See also:  - lock, - openAndLockDevice:mode:timeout:














Instance Methods

CRMassage
- (BOOL)CRMassage

Returns whether or not input carriage returns will be turned into newlines and output and echoed newlines will be turned a carriage return followed by a linefeed (this may differ from the actual stat if autoGet is disabled and the port has been modified directly using UNIX calls).  This flag is ignored in RAW mode, and no massaging occurs.

See also:  - setCRMassage:, - setAutoGetEnabled:




applyLmode:
- applyLmode:(const unsigned short *)arg

Takes the bitflags pointed at by arg and applies them to the serial port before making them the current settings.  If arg is NULL, then the current lmode settings will be applied to the port (meaningful only if autoSet has been disabled).  Returns self if the operation was a success and nil otherwise.

See also:  - fetchLmode:, - setAutoSetEnabled:




applyLtchars:
- applyLtchars:(const struct ltchars *)arg

Takes the settings in the structure pointed at by arg and applies them to the serial port before making them the current settings.  If arg is NULL, then the current ltchars settings will be applied to the port (meaningful only if autoSet has been disabled).  Returns self if the operation was a success and nil otherwise.

See also:  - fetchLtchars:, - setAutoSetEnabled:




applySettings::::::
- applySettings:(const int *)ldisc
:(const struct sgttyb *)arg1 
:(const struct tchars *)arg2 
:(const unsigned short *)lmode 
:(const struct ltchars *)arg4 
:(const struct winsize *)arg5

Takes the settings in the structures pointed at by the arguments and applies them to the serial port before making them the current settings.  If any argument is NULL, then the current settings for that structure will be applied to the port (meaningful only if autoSet has been disabled).  Returns self if the operation was a success and nil otherwise.

See also:  - fetchSettings::::::, - setAutoSetEnabled:




applySettings
- applySettings

Equivalent to applySettings:::::: with all arguments NULL.  This call is meaningless if autoSet is enabled.

See also:  - fetchSettings, - applySettings::::::, - setAutoSetEnabled:




applySgttyb:
- applySgttyb:(const struct sgttyb *)arg

Takes the settings in the structure pointed at by arg and applies them to the serial port before making them the current settings.  If arg is NULL, then the current sgttyb settings will be applied to the port (meaningful only if autoSet has been disabled).  Returns self if the operation was a success and nil otherwise.

See also:  - fetchSgttyb:, - setAutoSetEnabled:




applyTchars:
- applyTchars:(const struct tchars *)arg

Takes the settings in the structure pointed at by arg and applies them to the serial port before making them the current settings.  If arg is NULL, then the current tchars settings will be applied to the port (meaningful only if autoSet has been disabled).  Returns self if the operation was a success and nil otherwise.

See also:  - fetchTchars:, - setAutoSetEnabled:




applyWinsize:
- applyWinsize:(const struct winsize *)arg

Takes the settings in the structure pointed at by arg and applies them to the serial port before making them the current settings.  If arg is NULL, then the current winsize settings will be applied to the port (meaningful only if autoSet has been disabled).  Returns self if the operation was a success and nil otherwise.

See also:  - fetchWinsize:, - setAutoSetEnabled:




autoGetEnabled
- (BOOL)autoGetEnabled

Returns whether current port settings are automatically reloaded from the port when they are queried (default YES).  Doing this ensures that, even if the port has been altered using direct UNIX calls, the query will return the true state of the port.  Changing this flag to NO provides a slight speed improvement, but this is not recommended.

See also:  - setAutoGetEnabled:




autoSetEnabled
- (BOOL)autoSetEnabled

Returns whether current port settings are applied to the serial port when they are changed (default YES).  Setting this flag to NO allows you to configure baud rate, parity, etc. individually before applying all your changes to the port using applySettings.

Note that if autoSet is enabled, then the port settings will be fetched before they are modified whether or not autoGet is enabled.

See also:  - setAutoSetEnabled:




baudRate
- (int)baudRate

Returns the current baud rate (this is an enumerated type, not the baud rate itself).  This may differ from the actual baud rate if autoGet is disabled and the port has been modified directly using UNIX calls.

See also:  - numericBaudRate, - autoGetEnabled, - setBaudRate:




clearStatus
- clearStatus

Resets the status to LGD_SP_OK and sets the unix errno to 0.  Returns self.

See also:  - status, - statusString




close
- close

Closes the serial device, which must have been previously set using setDevice: and opened using openWithTimeout:.  Returns self if successful, and nil otherwise.

This call is seldom invoked directly, as the method unlockAndClose provides a more convenient way to stop using a device.

See also:  - openWithTimeout:, - unlockAndClose




continue
- continue

Sends a ªcontinueº signal to the serial port.  This is used to restart data transmission after it was stopped using the ªpauseº signal.  Returns self if successful, and nil otherwise.

See also:  - pause




copyFromZone:
- copyFromZone:(NXZone *)aZone

Allocates and returns a copy of the reciever.  The copy will be unlocked and closed and will have device NULL regardless of the current state of the reciever.




dataAvailable
- (BOOL)dataAvailable

Returns whether or not data is available to be read from the serial port.  If there is an error (the most common of which is that no port has been opened), then this method returns NO as well as setting the error flags.

See also:  - readBlock:size:all:




device
- (const char *)device

Returns the current serial device, or NULL if there is no current device.

See also:  - setDevice:, - openAndLockDevice:mode:timeout:




discipline
- (int)discipline

Returns the current line discipline (LGD_SP_OLD or LGD_SP_NEW).

See also:  - setDiscipline:, - fetchSettings




fetchLmode:
- fetchLmode:(unsigned short *)arg

Queries the serial device for its lmode settings and make them the current settings, then copies those settings into the bitflags pointed to by arg.  If arg is NULL, then the current settings will be fetched but not returned.  Returns self if the operation was a success and nil otherwise.

See also:  - applyLmode:




fetchLtchars:
- fetchLtchars:(struct ltchars *)arg

Queries the serial device for its ltchars settings and make them the current settings, then copies those settings into the structure pointed to by arg.  If arg is NULL, then the current settings will be fetched but not returned.  Returns self if the operation was a success and nil otherwise.

See also:  - applyLtchars:




fetchSettings
- fetchSettings

Equivalent to fetchSettings:::::: with all arguments set to NULL.  Returns self if successful, and nil otherwise.  If autoGet has been enabled (which is strongly reccommended) then the settings will be automatically brought up to date whenever a particular setting is requested, and this method need never be invoked.

See also:  - fetchSettings::::::, - applySettings




fetchSettings::::::
- fetchSettings:(int *)ldisc
:(struct sgttyb *)arg1 
:(struct tchars *)arg2 
:(unsigned short *)lmod 
:(struct ltchars *)arg4 
:(struct winsize *)arg5

Queries the serial device for its current settings, then copies those settings into the structures pointed at by arg1 ¼ arg5.  If any argument is NULL, then the current settings for that structure will be fetched, but not passed back.  Returns self if the operation was a success and nil otherwise.

See also:  - applySettings::::::




fetchSgttyb:
- fetchSgttyb:(struct sgttyb *)arg

Queries the serial device for its sgttyb settings and make them the current settings, then copies those settings into the structure pointed to by arg.  If arg is NULL, then the current settings will be fetched but not returned.  Returns self if the operation was a success and nil otherwise.

See also:  - applySgttyb:




fetchTchars:
- fetchTchars:(struct tchars *)arg

Queries the serial device for its tchars settings and make them the current settings, then copies those settings into the structure pointed to by arg.  If arg is NULL, then the current settings will be fetched but not returned.  Returns self if the operation was a success and nil otherwise.

See also:  - applyTchars:




fetchWinsize:
- fetchWinsize:(struct winsize *)arg

Queries the serial device for its winsize settings and make them the current settings, then copies those settings into the structure pointed to by arg.  If arg is NULL, then the current settings will be fetched but not returned.  Returns self if the operation was a success and nil otherwise.

See also:  - applyWinsize:




_fileDescriptor
- (int)_fileDescriptor

Returns the file descriptor associated with the currently opened device, or -1 if there is no open device.  Directly manipulating this file descriptor is not reccommended, and unexpected behaviour may result from such tamperings.




flush
- flush

Discards all characters waiting to be read from the device as well as those waiting to be written to the device.  Returns self if successful, and nil otherwise.

See also:  - flushInput, - flushOutput




flushInput
- flushInput

Discards all characters waiting to be read from the device.  Returns self if successful, and nil otherwise.

See also:  - flushOutput, - flush




flushOutput
- flushOutput

Discards all characters waiting to be written to the device.  Returns self if successful, and nil otherwise.

See also:  - flushInput, - flush




free
- free

Frees the reciever and any resources it was consuming.  If the device was open it is closed, and if locked the lock is removed.

See also:  - close, - unlock




getBlock:size:all:
- (int)getBlock:(char *)buffer size:(int)bufSize all:(BOOL)yn

Reads at most bufSize characters from the serial device and stores them in buffer.  Returns the number of characters read, or -1 if there was an error which prevented any characters from being read.

If the all flag is YES, then the call will not return until bufSize characters have been read or there has been an error.

Since a return value of less than bufSize can have two meanings (there was an error, or there were no more characters to read and the all flag was NO), it is strongly recommended that status be checked after invoking this method.

See also:  - sendBlock:size:all:




getCharacter:
- (int)getCharacter:(int *)aCharacter

Reads a single character from the port and stores it in aCharacter (stores EOF if unable to read a characters).  Returns 1 if a character was successfully read, 0 if there was no data waiting at the port, and -1 if there was an error.

See also:  - getBlock:size:all:




getString:max:
- (int)getString:(char *)buffer max:(int)bufSize

Equivalent to getString:max:termChars: with terminating characters `\n' and `\r'.

See also:  - getString:max:termChars:




getString:max:termChars:
- (int)getString:(char *)buffer max:(int)bufSize termChars:(const char *)set

Reads characters from the device until one of the characters in the null-terminated set (the `\0' character is always included in the set) has been encountered or there are no more characters available to be read.  The first bufSize-1 characters (including the terminating character) will be stored in buffer, followed by a `\0' character.

Returns the number of characters read, or -1 if there was an error.  Note that the return value may exceed bufSize-1, but the excess characters will have been discarded.

See also:  - getBlock:size:all:




init
- init

Initializes and returns the reciever, a newly-allocated LGDSerialPort instance.  The reciever initially has no device set, and is closed and unlocked.

See also:  - openAndLockDevice:mode:timeout:




isDeviceAvailable:
- (BOOL)isDeviceAvailable:(const char *)device

Returns whether there is a lock on device.  Even if there is no explicit lock set, an attempt to open the device may still fail if the device has been opened without being locked, or if another device which uses the same serial port is open.  See openAndLockDevice:mode:timeout: for a list of available devices.

Note that this call checks for the existence of lock files.  If the device was locked by the creation of a lock directory, then this call will falsely return that the device is available.  This situation should never arise, since directories are not valid device locks.

See also:  - lock, + getLockFile:forDevice:




isLocked
- (BOOL)isLocked

Returns whether the reciever has a lock on its device.

See also:  + getLockFile:forDevice:, - lock, - unlock, - unlockAndClose




isOpen
- (BOOL)isOpen

Returns whether the reciever has opened its device.

See also:  - openWithTimeout:, - close, - openAndLockDevice:mode:timeout:




lock
- lock

Attempts to lock the current device.  Returns self if successful, and nil otherwise.  It is strongly reccommended that devices be locked before they are opened to prevent multiple tasks from competing for the bytes as they arrive.

This call is seldom invoked directly, as the method openAndLockDevice:mode:timeout: provides a more convenient way to start using a device.

See also:  - unlock, + getLockFile:forDevice:, + writeLockFileContents:forDevice:, - openAndLockDevice:mode:timeout:




lowerBreak
- lowerBreak

Lowers the BREAK line of the serial port.  Returns self if successful, and nil otherwise.

See also:  - raiseBreak




lowerDTR
- lowerDTR

Lowers the DTR (data terminal ready) line of the serial port.  Returns self if successful, and nil otherwise.

See also:  - raiseDTR




numericBaudRate
- (int)numericBaudRate

Returns the current baud rate as an integer value (1200, 9600, etc.).  This may differ from the actual baud rate if autoGet is disabled and the port has been modified directly using UNIX calls.

See also:  - autoGetEnabled, - baudRate




mode
- (int)mode

Returns the current mode of the reciever (this may differ from the actual baud rate if autoGet is disabled and the port has been modified directly using UNIX calls).  This mode will be one of
		LGD_SP_RAW
		LGD_SP_CBREAK
		LGD_SP_COOKED
Raw mode is used when binary data is to be transmitted, and cooked mode when performing interactive ASCII operations.  Cbreak mode is seldom used.

See also:  - setMode, - setAutoGetEnabled:




open
- open

Attempts to open the current device for reading and writing.  The method will not return until either the device has become available and been opened or there is an error.  Returns self if successful, and nil otherwise.

This call is seldom invoked directly, as the method openAndLockDevice:mode:timeout: provides a more convenient way to start using a device.

See also:  - openWithTimeout:, - setDevice:, + getDeviceFile:forDevice:, - openAndLockDevice:mode:timeout:




openAndLockDevice:mode:timeout:
- openAndLockDevice:(const char *)device
mode:(int)mode
timeout:(long)seconds

This is the standard way to prepare a serial device for use.  Device is made the current device (or the current device is unchanged if device is NULL), the port is opened and locked, and has its mode set to one of LGD_SP_RAW, LGD_SP_CBREAK, or LGD_SP_COOKED.  Finally, a disconnect signal is sent to ensure that a clean connection is formed.  A negative timeout value indicates that the open attempt should never time out.  Returns self if successful, and nil otherwise.  If nil is returned, the status flag will be LGD_SP_OK if the call timed out, and set to an appropriate error value otherwise.

The commonly used devices are
	ttya	ttyb	Used for incoming connections from directly connected terminals without flow control.
	ttyfa	ttyfb	Used for incoming connections from directly connected terminals with flow control.
	ttyda	ttydb	Used for incoming connections from modems.
	ttydfa	ttydfb	Used by systems whose hardware supports RTS/CTS flow control (68040 and later) for incoming connections from modems.
	cua	cub	Used for outgoing connections to modems.
	cufa	cufb	Used by systems whose hardware supports RTS/CTS flow control (68040 and later) for outgoing connections to modems.

See also:  - unlockAndClose, - setDevice:, - lock, - openWithTimeout:, - setMode:, - sendDisconnect




openWithTimeout:
- openWithTimeout:(long)seconds

Attempts to open the current device for reading and writing.  The open will fail if the device is not obtained within the time interval specified by seconds (a negative value indicates that the open attempt should not time out).  Returns self if successful, and nil otherwise.  If the open fails, it is important to check the status flag.  The flag will be LGD_SP_OK if the open failed due to timeout and LGD_SP_ALREADYOPEN or LGD_SP_ERRNO otherwise.

This call is seldom invoked directly, as the method openAndLockDevice:mode:timeout: provides a more convenient way to start using a device.

See also:  - setDevice:, + getDeviceFile:forDevice:, - openAndLockDevice:mode:timeout:




parity
- (int)parity

Returns the current parity used to communicate with the device (this may differ from the actual baud rate if autoGet is disabled and the port has been modified directly using UNIX calls).  The parity will be one of
		LGD_SP_EVENPARITY
		LGD_SP_ODDPARITY
		LGD_SP_ZEROPARITY
		LGD_SP_NOPARITY

See also:  - setParity:, - setAutoGetEnabled:




pause
- pause

Sends a ªstopº signal to the device, signalling the hardware on the other end of the serial line to stop sending data until a ªstartº signal is sent.  Returns self if successful, and nil otherwise.

See also:  - continue




raiseBreak
- raiseBreak

Raises the BREAK line on the serial device.  Returns self if successful, nil if unsuccessful.

See also:  - lowerBreak




raiseDTR
- raiseDTR

Raises the DTR (data terminal ready) line of the serial device.  Returns self if successful, and nil if unsuccessful.

See also:  - lowerDTR




read:
- read:(NXTypedStream *)stream

Unarchives the reciever from stream.  The reciever will have the device that was set when it was archived, but will be unlocked and closed.

See also:  - write:




sendBlock:size:all:
- (int)sendBlock:(const char *)buffer size:(int)size all:(BOOL)yn

Attempts to write bufSize characters from buffer to the serial device.  Returns the number of characters written, or -1 if there was an error which prevented any characters from being written.

If the all flag is YES, then the call will not return until bufSize characters have been written or there has been an error.

Since a return value of less than bufSize can have two meanings (there was an error, or the device signalled that it could accept no more characters and the all flag was NO), it is strongly recommended that status be checked after invoking this method.

See also:  - getBlock:size:all:




sendBreak
- sendBreak

Sends a BREAK signal to the connected machine.  Returns self if successful, and nil if unsuccessful.

See also:  - raiseBreak, - lowerBreak




sendCharacter:
- (int)sendCharacter:(int)aCharacter

Attempts to send aCharacter to the serial device.  Returns 1 if successful, 0 if the device is not accepting data, and -1 if there was an error.

See also:  - sendBlock:size:all:




sendDisconnect
- sendDisconnect

Sends a disconnect signal to the connected machine, causing a hangup.  Returns self if successful, and nil if unsuccessful.

See also:  - lowerDTR, - raiseDTR




sendString:
- (int)sendString:(const char *)aString

Equivalent to sendString:withTrailer: with trailing string ª\rº.

See also:  - sendString:withTrailer:




sendString:withTrailer:
- (int)sendString:(const char *)aString withTrailer:(const char *)trailer

Attempts to send aString to the serial device, and if successful, attempts to send trailer.  Returns the number of bytes written if successful (which will equal strlen(aString)+strlen(trailer) ); returns -1 otherwise.

See also:  - sendBlock:size:all:




setAutoGetEnabled:
- setAutoGetEnabled:(BOOL)yn

Determines whether current port settings are automatically reloaded from the port when they are queried (default YES).  Doing this ensures that, even if the port has been altered using direct UNIX calls, the query will return the true state of the port.  Changing this flag to NO provides a slight speed improvement, but this is not recommended.  Returns self.

See also:  - autoGetEnabled:




setAutoSetEnabled:
- setAutoSetEnabled:(BOOL)yn

Determines whether current port settings are applied to the serial port when they are changed (default YES).  Setting this flag to NO allows you to configure baud rate, parity, etc. individually before applying all your changes to the port using applySettings.  Returns self.

Note that if autoSet is enabled, then the port settings will be fetched before they are modified whether or not autoGet is enabled.

See also:  - autoSetEnabled:




setBaudRate:
- setBaudRate:(int)rate

Sets the baud rate used by the serial device.  Rate must be one of
		LGD_SP_B0
		LGD_SP_B50
		LGD_SP_B75
		LGD_SP_B110
		LGD_SP_B134
		LGD_SP_B150
		LGD_SP_B200
		LGD_SP_B300
		LGD_SP_B600
		LGD_SP_B1200
		LGD_SP_B1800
		LGD_SP_B2400
		LGD_SP_B4800
		LGD_SP_B9600
If autoSet has been disabled, then the baud rate changes will not be applied to the device until applySettings is invoked.  Returns self if successful, nil if unsuccessful.


See also:  - baudRate, - setAutoSetEnabled:, - applySettings, - applySgttyb:




setCRMassage:
- setCRMassage:(BOOL)yn

Determines whether or not input carriage returns will be turned into newlines and output and echoed newlines will be turned a carriage return followed by a linefeed.  This flag is ignored in RAW mode, and CR massage does not take place.

If autoSet has been disabled, then the massage flag changes will not be applied to the device until applySettings is invoked.  Returns self if successful, nil if unsuccessful.


See also:  - CRMassage, - setAutoSetEnabled:, - applySettings, - applySgttyb:




setDevice:
- setDevice:(const char *)device

Sets device to be the current serial device (see openAndLockDevice:mode:timeout: fora list of common devices). No action is taken at this point, but any subsequent operations will affect device.  This call will fail with LGD_SP_ALREADYOPEN if the device is changed while open or locked.  Returns self.

This call is seldom invoked directly, as the methods openAndLockDevice:mode:timeout: and unlockAndClose provide more convenient ways to start and stop using a device.

See also:  - openAndLockDevice:mode:timeout:, - unlockAndClose




setDiscipline
- setDiscipline:(int)aDiscipline

Sets the line discipline to be one of
		LGD_SP_OLD
		LGD_SP_NEW
There is virtually never a reason to change the line discipline from its default of LGD_SP_NEW.

If autoSet has been disabled, then the discipline changes will not be applied to the device until applySettings is invoked.  Returns self if successful, nil if unsuccessful.

See also:  - discipline, - setAutoSetEnabled:, - applySettings




setDuplex:
- setDuplex:(int)duplex

Sets the serial port to be one of
		LGD_SP_HALFDUPLEX
		LGD_SP_FULLDUPLEX
In full-duplex mode, any characters sent to the serial device will also be echoed back as input.

If autoSet has been disabled, then the duplex flag changes will not be applied to the device until applySettings is invoked.  Returns self if successful, nil if unsuccessful.


See also:  - duplex, - setAutoSetEnabled:, - applySettings, - applySgttyb:




setMode:
- setMode:(int)mode

Sets the mode of the serial port to one of
		LGD_SP_RAW
		LGD_SP_CBREAK
		LGD_SP_COOKED

In RAW mode, no input or output processing is done ± the characters are made available to the process connected through the device as soon as they are sent, and characters sent by the foreign process are immediately available.  Carriage-return massage does not take place in RAW mode.  This is the mode generally used for raw data transfer.

In CBREAK mode, flow control and interrupt processing take place, but non-control characters are made immediately available to the foreign process.

In COOKED mode (the mode terminals generally operate under), data is collected, but not sent to the process on the other end of the device until a newline is sent.

If autoSet has been disabled, then the mode changes will not be applied to the device until applySettings is invoked.  Returns self if successful, nil if unsuccessful.


See also:  - mode, - openAndLockDevice:mode:timeout, - setAutoSetEnabled:, - applySettings, - applySgttyb:




setNumericBaudRate:
- setNumericBaudRate:(int)rate

Sets the baud rate used by the serial device.  The baud rate will be set to the fastest setting which is both valid and not greater than rate.  For instance, attempting to set a baud rate of 5000 would result in an actual baud rate of 4800.  If autoSet has been disabled, then the baud rate changes will not be applied to the device until applySettings is invoked.  Returns self if successful, nil if unsuccessful.


See also:  - setBaudRate:, - setAutoSetEnabled:, - applySettings, - applySgttyb:




setParity:
- setParity:(int)parity

Sets the parity of the serial device to be one of
		LGD_SP_EVENPARITY
		LGD_SP_ODDPARITY
		LGD_SP_ZEROPARITY
		LGD_SP_NOPARITY
In zero parity and no parity modes, characters are accepted regardless of the parity bit, but are sent out with the parity bit either cleared (zero parity) or set (no parity).

If autoSet has been disabled, then the massage flag changes will not be applied to the device until applySettings is invoked.  Returns self if successful, nil if unsuccessful.


See also:  - parity, - setAutoSetEnabled:, - applySettings, - applySgttyb:




status
- (int)status

Returns the most recent error flag generated by the reciever.  This flag remains set until explicitly cleared, or until replaced by a new error, so it is a good idea to clear the status flag after checking for errors.  The status may  be one of
	LGD_SP_OK	No error
	LGD_SP_DEVICEINUSE	Attempt to lock a device which has been already been locked by someone else.
	LGD_SP_ALREADYLOCKED	Attempt to lock the reciever when it is already locked (this is NOT the same as attempting to lock a device when it has already been locked by another process).
	LGD_SP_NOTLOCKED	Attempt to unlock the reciever when it has not been locked.
	LGD_SP_ALREADYOPEN	Attempt to open the reciever when it is already open (this is NOT the same as attempting to open a device when the device is already open).
	LGD_SP_NOTOPEN	Attempt to perform some operation (reading, writing, setting parameters) without an open device.
	LGD_SP_ERRNO	Command raised a unix error.  See the global variable errno for details (error numbers and their meanings are described in <errno.h>)

See also:  - clearStatus, - statusString




statusString
- (const char *)statusString

Returns a string describing the error status, suitable for display in an alert panel or entering into a log file.

See also:  - clearStatus, - status




unlock
- unlock

Unlocks the current device by erasing the lock file.  Returns self, or null if unable to remove lock file.

This call is seldom invoked directly, as the method unlockAndClose provides a more convenient way to stop using a device.

See also:  - lock, - unlockAndClose, + getLockFile:forDevice:




unlockAndClose
- unlockAndClose

This method is the standard way to stop using a serial device.  It disconnects from the foreign machine, closes the port, unlocks the device.  The current device is not changed.  Returns self if successful, and nil otherwise.

See also:  - sendDisconnect, - flush, - close, - unlock, - openAndLockDevice:mode:timeout:




write:
- write:(NXTypedStream *)stream

Archives the reciever to stream.  When unarchived, the new object will have the device that was set when the reciever was archived, but will be unlocked and closed.

See also:  - read:












Constants and Defined Types

// Status flags
#define LGD_SP_OK		0x0000
#define LGD_SP_DEVICEINUSE	0x0001
#define LGD_SP_ALREADYLOCKED	0x0002
#define LGD_SP_NOTLOCKED	0x0003
#define LGD_SP_ALREADYOPEN	0x0004
#define LGD_SP_NOTOPEN		0x0005
#define LGD_SP_ERRNO		0x0006

// Disciplines
// (Referenced definitions found in <sgtty.h>)
#define LGD_SP_NEW	NTTYDISC
#define LGD_SP_OLD	OTTYDISC

// Modes
#define LGD_SP_RAW		0x0000
#define LGD_SP_CBREAK		0x0001
#define LGD_SP_COOKED		0x0002

// Speeds
// (Referenced definitions found in <sgtty.h>)
#define LGD_SP_B0		B0
#define LGD_SP_B50		B50
#define LGD_SP_B75		B75
#define LGD_SP_B110		B110
#define LGD_SP_B134		B134
#define LGD_SP_B150		B150
#define LGD_SP_B200		B200
#define LGD_SP_B300		B300
#define LGD_SP_B600		B600
#define LGD_SP_B1200		B1200
#define LGD_SP_B1800		B1800
#define LGD_SP_B2400		B2400
#define LGD_SP_B4800		B4800
#define LGD_SP_B9600		B9600

// Parity
// (Referenced definitions found in <sgtty.h>)
#define LGD_SP_EVENPARITY	EVENP
#define LGD_SP_ODDPARITY	ODDP
#define LGD_SP_ZEROPARITY	0x0000
#define LGD_SP_NOPARITY	(EVENP|ODDP)

// Duplex
#define LGD_SP_HALFDUPLEX	0x0000
#define LGD_SP_FULLDUPLEX	0x0001

These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.