Release 1.0 Copyright © 1994 Eric Norum. All rights reserved.
MiscXmodem |
Inherits From: | Object | |
Declared In: | <misckit/MiscXmodem.h> |
Class Description |
The MiscXmodem class implements the XMODEM, XMODEM-CRC and XMODEM-1k-CRC serial-line file transfer
prtocols. A complete description of these protocols can be found in, XMODEM/YMODEM PROTOCOL REFERENCE
-- A compendium of documents describing the XMODEM and YMODEM File Transfer Protocols, Chuck Forsberg,
Omen Technology Incorporated, Portland, Oregon, 1988.
Objects of this class do not modify the serial line settings in any way. Before invoking the data transfer methods (sendSerialPort:toStream:, sendStream:toSerialPort:) the serial line must be configured to provide an 8-bit-clean path at the appropriate speed. MiscXmodem objects are multithreaded but the sub-thread makes no Objective-C calls, so applications using these objects do not have to call objc_setMultithreaded(). Applications should however use cthread_errno() rather than errno, at least while data transfer is in progress. |
Instance Variables |
BOOL isActive; BOOL isText; BOOL use1kPackets; BOOL isDynamicCheck; BOOL useCRC; MiscSerialPort *serialPort; BOOL serialPortWasSuspended; int fd; fd_set checkFdSet; NXStream *stream; cthread_t xmodemThread; port_t messagePort; port_t replyPort; id delegate; unsigned char packetBuffer[1024+5]; unsigned char smallPacketData[1024]; int smallPacketIndex; int smallPacketCount; BOOLnewlineFlag; BOOL isDynamicCheckPacket; int lastPacketNumber; int goodPacketCount; float kbytes; |
isActive | YES if a data transfer operation in in progress. | |
isText | YES if data will be treated as ASCII text. | |
use1kPackets | YES if data transmission will use large packets. | |
isDynamicCheck | YES if error checking method will be determined dynamically. | |
useCRC | YES if 16-bit CRC error checking method is in use. | |
MiscSerialPort | Serial port object to be used for data transfer. | |
serialPortWasSuspended | Remember whether or not to continue serial port object when data transfer is complete. | |
fd | Serial line file descriptor. | |
checkFdSet | Select(2) file descriptor bitmap. | |
stream | The stream to be used for data transfer. | |
xmodemThread | Data transfer thread. | |
messagePort | Mach port for messages from data transfer thread to main thread. | |
replyPort | Mach port for messages from main thread to data transfer thread. | |
delegate | The object that responds to notification messages. | |
packetBuffer | Current incoming or outgoing packet. | |
smallPacketData | Storage for small packet transmission. | |
smallPacketIndex | Index of next small packet data item to transmit. | |
smallPacketCount | Number of data bytes in smallPacketData. | |
newlineFlag | YES if a newline character needs to be transmitted (text mode data transfers). | |
isDynamicCheckPacket | YES if the next packet will be used to determine the error-checking method. | |
lastPacketNumber | Packet number (0-255) of most recent successfully-received packet. | |
goodPacketCount | Number of packets successfully transferred. | |
kbytes | Number of kbytes of data successfully transferred. |
Method Types |
Initializing and freeing instances | - init - free | |
Data transfer options | - setFileTypeText: - xmodemSet1kPackets: - xmodemSetCheckTypeDynamic: - xmodemSetCheckTypeCRC: - isFileTypeText - xmodemIs1kPackets - xmodemIsCheckTypeDynamic - xmodemIsCheckTypeCRC | |
Data transfer operations | - sendToSerialPort:fromStream: - sendToStream:fromSerialPort: - isActive | |
Delegate | - setDelegate: - delegate - didTransferPacket:kbytes: - didRetryNumber: - didFinish: |
Instance Methods |
delegate |
-delegate |
Returns the object's delegate.
free |
-free |
Cancels the data transfer operation, if any, and frees the object.
init |
-init |
Initializes a new MiscXmodem instance. The default settings are text files, 1k packets, and dynamic selection of error
checking method.
setDelegate: |
-setDelegate:id |
Sets the object's delegate. Delegate objects are sent messages describing the progress of data transfer operations.
See also: - didFinish:, - didTransferPacket:kbytes:, - didRetryNumber:
didFinish: |
-didFinish:(const char *)failureCode |
Sent to the delegate when data transfer operation completes. If the transfer completed successfully, the failureCode
string will be empty (""), otherwise the string will describe the condition that caused the transfer to fail.
didRetryNumber: |
-didRetryNumber:(int)anInt |
Sent to the delegate when the data transfer operation retries a packet transfer. The argument is the number of times
that the current packet has been retried.
didTransferPacket:kbytes: |
-didTransferPacket:(int)anInt kbytes:(float)aFloat |
Sent to the delegate when the a packet is successfully transferred. The arguments are the number of packets and the
amount of data (in kbytes) that have been transferred so far.
xmodemIs1kPackets |
-(BOOL)xmodemIs1kPackets |
Returns YES if data transmission will use 1k packets, NO if it will use only 128-byte packets. The default value is
YES.
See also: - xmodemSet1kPackets:
isActive |
-(BOOL)isActive |
Returns YES if the MiscXmodem object is in the process of transferring data between the seria port and the stream,
NO if it is not.
See also: - sendFromSerialPort:toStream:, - sendFromStream:toSerialPort:, - xmodemIsDone:
xmodemIsCheckTypeCRC |
-(BOOL)xmodemIsCheckTypeCRC |
Returns YES if data reception will use CRC error checking, NO if it will use a checksum. The default value is YES.
See also: - xmodemSet1kPackets:, - xmodemSetDynamicCheck:
xmodemIsCheckTypeDynamic |
-(BOOL)xmodemIsCheckTypeDynamic |
Returns YES if data reception will first attempt to use CRC error checking and automatically revert to use a checksum
if the sender does not support CRC error checking. Returns NO if data reception will not dynamically adapt to the
sender's preference. The default value is YES.
See also: - xmodemSetDynamicCheck, - xmodemSet1kPackets
isFileTypeText |
-(BOOL)isFileTypeText |
Returns YES if data transfer will convert files to/from DOS text format. Returns NO if data will be transferred
unmodified.
See also: - setFileTypeText
sendToStream:fromSerialPort: |
-sendToStream:(NXStream *)aStream fromSerialPort:(int)ttyFd |
Spawns a subthread to perform a data reception operation and returns self if a transfer is not already in progress. Does
nothing, and returns nil, if a transfer is already in progress. The application must not use the stream or the tty until the
transfer is complete.
See also: - isActive, - didFinish:, - didTransferPacket:kbytes:, - didRetryNumber:
sendToSerialPort:fromStream: |
-sendToSerialPort:(int)ttyFd fromStream:(NXStream *)aStream |
Spawns a subthread to perform a data transmission operation and returns self if a transfer is not already in progress.
Does nothing, and returns nil, if a transfer is already in progress. The application must not use the stream or the tty
until the transfer is complete.
See also: - isActive, - didFinish:, - didTransferPacket:kbytes:, - didRetryNumber:
xmodemSet1kPackets: |
-xmodemSet1kPackets:(BOOL)flag |
Control the use of 1k packets when transmitting. If flag is YES, 1-kbyte packets will be transmitted until there are
fewer than 1024 bytes left to send at which point 128-byte packets will be used. If flag is NO, only 128-byte packets
will be used. Both 128-byte and 1-kbyte packets are always accepted when receiving.
See also: - xmodemIs1kPackets
xmodemSetCheckTypeCRC: |
-xmodemSetCheckTypeCRC:(BOOL)flag |
Select the error checking method to be used. If flag is YES, a 16-bit CRC error checking code will be used. If flag is
NO, a simple 8-bit checksum will be used. This option is used only when receiving a file, since data transmission
operations always adapts to the check method chosen by the receiver.
See also: - xmodemIsCheckTypeCRC, -xmodemSetCheckTypeDynamic
xmodemSetCheckTypeDynamic: |
-xmodemSetCheckTypeDynamic:(BOOL)flag |
If flag is YES, data reception operations will first try to use a 16-bit CRC error checking code. If the sender does not
support CRC, the receiver will automatically revert to an 8-bit checksum. If flag is YES, data reception operations will
use the check method specified by xmodemSetCheckTypeCRC:.
See also: - xmodemIsCheckTypeDynamic, -xmodemSetCheckTypeCRC:
setFileTypeText: |
-setFileTypeText:(BOOL)flag |
Controls the interpretation of transferred data. If flag is NO, data will be transferred unmodified. Data will be padded
to a 128-byte boundary so the contents of a data transfer operation can grow by up to 127 bytes. If flag is YES, data
will be transferred in DOS text format. On transmission, <newline> characters will be converted to <carriage
return><newline> pairs and a control-Z character (ASCII 032) will be used to mark the end of the data. On reception, <carriage return> characters will be removed and a control-Z and subsequent characters will not be added to the stream. See also: - isFileTypeText |