|
|
|
|
9
Serial Communication.
"Serial Library" for the library name to get the serial library reference number. This reference number is used with all subsequent serial manager calls. The system software automatically installs the serial library during system initialization.
SysLibFind), 0 (zero) for the port number, and the desired baud rate. An error code of 0 (zero) or -serErrAlreadyOpen indicates that the port was successfully opened.
SerOpen is called, the port's open count is incremented and an error code of serErrAlreadyOpen is returned. This ability to open the serial port multiple times allows cooperating tasks to share the serial port.
serErrAlreadyOpen is returned. Error codes other than 0 (zero) or serErrAlreadyOpen indicate failure. The application must open the serial port before making other serial manager calls.
SerClose. Every successful call to SerOpen must eventually be paired with a call to SerClose. Because an open serial port consumes more energy from the device's batteries, it is essential not to keep the port open any longer than necessary.
serErrLineErr if any line errors are pending. Applications should therefore check the result of serial manager function calls and call SerClearErr if line error(s) occurred.
SerSend blocks until all data are transferred to the UART or a timeout error (if CTS handshaking is enabled) occurs. If your software needs to detect when all data has been transmitted, consider calling SerSendWait.
NOTE: BothSerSendandSerReceivewere enhanced in version 2.0 of the system. See the function descriptions for more information. The older versions are still available as SerSend10 and SerReceive10.
SerSendWait. SerSendWait blocks until all pending data is transmitted or a CTS timeout error occurs (if CTS handshaking is enabled).
SerReceive, specifying a buffer, the number of bytes desired, and the interbyte time out. This call blocks until all the requested data have been received or an error occurs.
(see below) to get the number of bytes presently in the receive queue and then call SerReceive, specifying the number of bytes desired. Because SerReceive returns immediately without any data if line errors are pending, it is important to acknowledge the detection of line errors by calling SerClearErr.
SerClearErr to detect any line errors. See also SerReceiveCheck and SerSetReceiveBuffer.
SerReceiveCheck.
SerSetReceiveBuffer, passing 0 (zero) for the buffer size. The serial manager does not free the custom receive queue.
EvtResetAutoOffTimer each time a new packet is received. Note that this facility is not part of the serial manager but part of the event manager. For more information, see "Auto-Off Control" .
SerCtlEnum, whose elements are described in Table 9.1.
NOTE: The new serial manager is not available on all Palm devices. It is available by flash ROM update on Palm III™ and upgraded PalmPilot™ devices and some later devices. Before making any new serial manager calls, you must ensure that it is present.
err = FtrGet(sysFileCSerialMgr, sysFtrNewSerialPresent, &value);value parameter will be non-zero and the returned error should also be zero (for no error).
SrmOpen call returns a unique port ID for the open port. This port ID is required to perform any other new serial manager functions. If the returned port ID is NULL or an error is returned by the SrmOpen function, the returned port ID should be considered invalid. Once the SrmOpen call is made successfully, it indicates that the new serial manager has successfully allocated internal structures to maintain the port and has successfully loaded the serial driver for this port.
SrmOpen) or background connection ($8000 = Cradle Port, RS-232 serial
$800n = reserved for future types of ports
`u328' specifies the cradle port using the 68328 UART
`u650' specifies the IR port on an upgraded Palm III device
`ircm' specifies the IRComm virtual port
Note that other four-character codes will be added in the future
SrmClose returns no error, it indicates that the new serial manager has successfully closed the driver and deallocated the data structures used for maintaining the port.
SrmReceiveWait returns, you can call SrmReceiveWait functions, waiting for serial data to arrive on the port, without allowing the Palm OS to obtain time to execute other tasks running in the same thread (by calling EvtGetEvent and SysHandleEvent). Virtual devices often run in the same thread as applications and this can prevent virtual devices and other serial related code from properly handling received data.
SrmGetDeviceInfo call, until an error is returned.
SrmGetStatus is called to retrieve the line errors for the port if some of the send and receive functions return a serErrLineErr error code. #include <Pilot.h> // all the system toolbox headers#include <SerialMgr.h>#define k2KBytes 2048/************************************************************** FUNCTION: RcvSerialData** DESCRIPTION: An example of how to receive a large chunk of data* from the Serial Manager. This function is useful if the app* knows it must receive all this data before moving on. The* YourDrainEventQueue() function is a chance for the application* to call EvtGetEvent and handle other application events.* Receiving data whenever it's available during idle events* might be done differently than this sample.** PARAMETERS: * thePort -> valid portID for an open serial port.* rcvDataP -> pointer to a buffer to put the received data.* bufSize <-> pointer to the size of rcvBuffer and returns* the number of bytes read.* *************************************************************/Err RcvSerialData(UInt16 thePort, UInt8 *rcvDataP, UInt32 *bufSizeP){UInt32 bytesLeft, maxRcvBlkSize, bytesRcvd, waitTime, totalRcvBytes = 0;UInt8 *newRcvBuffer;UInt16 dataLen = sizeof(UInt32);Err* error; // The default receive buffer is only 512 bytes; increase it if // necessary. The following lines are just an example of how to // do it, but its necessity depends on the ability of the code // to retrieve data in a timely manner. newRcvBuffer = MemPtrNew(k2KBytes); // Allocate new rcv buffer. if (newRcvBuffer) // Set new rcv buffer. error = SrmSetReceiveBuffer(thePort, newRcvBuffer, k2KBytes); if (error) goto Exit; else return memErrNotEnoughSpace; // Initialize the maximum bytes to receive at one time. maxRcvBlkSize = k2KBytes; // Remember how many bytes are left to receive. bytesLeft = *bufSizeP; // Only wait 1/5 of a second for bytes to arrive. waitTime = SysTicksPerSecond() / 5; // Now loop while getting blocks of data and filling the buffer. do { // Is the max size larger then the number of bytes left? if (bytesLeft < maxRcvBlkSize) // Yes, so change the rcv block amount. maxRcvBlkSize = bytesLeft; // Try to receive as much data as possible, // but wait only one second for it. bytesRcvd = SrmReceive(thePort, rcvDataP, maxRcvBlkSize, waitTime, &error); // Remember the total number of bytes received. totalRcvBytes += bytesRcvd; // Figure how many bytes are left to receive. bytesLeft -= bytesRcvd; rcvDataP += bytesRcvd; // Advance the rcvDataP. // If there was a timeout and no data came through... if ((error == serErrTimeOut) && (bytesRcvd == 0)) goto Exit; // ...bail out and report the error. // If there's some other error, bail out. if ((error) && (error != serErrTimeOut)) goto Exit; // Call a function to handle any pending events because // someone might press the cancel button. // YourDrainEventQueue(); // Continue receiving data until all data has been received. } while (bytesLeft); // Clearing the receive buffer can also be done right before // the port is to be closed. // Set back the default buffer when we're done. SrmSetReceiveBuffer(thePort, 0L, 0); MemPtrFree(newRcvBuffer); // Free the space. Exit: *bufSizeP = totalRcvBytes; return error;}
NOTE: Creator types with all lowercase letters are reserved by Palm Computing. For more information about assigning and registering creator types, see "Assigning a Creator ID" .
__Startup__ function of the code resource. When the code resource is loaded, the new serial manager jumps to the beginning of the code resource and begins execution at DrvEntryPoint. This function is called at system restart, when the new serial manager is building a database of installed drivers and their capabilities, and when a serial port is opened.SrmControl function to the level of the hardware. SdrvrReadChar function in assembly language.saveDataProc function (passed to SdrvOpen), which handles reading the data from the UART by calling the SdrvReadChar function. It's best to implement the SdrvISP function in assembly language.__Startup__ function of the code resource. When the code resource is loaded, the new serial manager jumps to the beginning of the code resource and begins execution at DrvEntryPoint. This function is called at system restart, when the new serial manager is building a database of installed drivers and their capabilities, and when a virtual port is opened.SrmControl function to the level of the virtual device.
NOTE: The connection manager is not available on all Palm devices. It is available by flash ROM update on Palm III and upgraded PalmPilot devices and some later devices. Before making any connection manager calls, you must ensure that it is present.
slkErrAlreadyOpen. The return value slkErrAlreadyOpen indicates that the serial link manager has already been opened (most likely by another task). Other error codes indicate failure.
SlkClose may be called only if SlkOpen returned 0 (zero) or slkErrAlreadyOpen. When the open count reaches zero, SlkClose frees resources allocated by SlkOpen.
SlkClose), a pointer to a memory location for returning the socket ID, and a Boolean indicating whether the socket is static or dynamic. If a static socket is being opened, the memory location for the socket ID must contain the desired socket number. If opening a dynamic socket, the new socket ID is returned in the passed memory location. Sharing of sockets is not supported. Success is indicated by an error code of 0 (zero). For information about static and dynamic socket IDs, see "Socket ID Assignment" .
SlkSocketRefNum. The socket must already be open. To obtain the port ID for a socket, if you are using the new serial manager, call SlkSocketPortID.
SlkSocketListenType structure. Because the serial link manager does not make a copy of the SlkSocketListenType structure but instead saves the pointer passed to it, the structure may not be an automatic variable (that is, allocated on the stack). The SlkSocketListenType structure may be a global variable in an application or a locked chunk allocated from the dynamic heap. The SlkSocketListenType structure specifies pointers to the socket listener procedure and the data buffers for dispatching packets destined for this socket. Pointers to two buffers must be specified:
SlkPktHeaderType). SlkSocketListenType structure or the buffers when the socket is closed; freeing them is the responsibility of the application. For this mechanism to function, some task needs to assume the responsibility to "drive" the serial link manager receiver by periodically calling SlkReceivePacket.
SlkPktHeaderType) and a pointer to an array of SlkWriteDataType structures. SlkSendPacket stuffs the signature, client data size, and the checksum fields of the packet header. The caller must fill in all other packet header fields. If the transaction ID field is set to 0 (zero), the serial link manager automatically generates and stuffs a new non-zero transaction ID. The array of SlkWriteDataType structures enables the caller to specify the client data part of the packet as a list of noncontiguous blocks. The end of list is indicated by an array element with the size field set to 0 (zero). Listing 3.1 incorporates the processes described in this section.
Err err;SlkPktHeaderType sendHdr; //serial link packet headerSlkWriteDataType writeList[2]; //serial link write data segmentsUInt8 body[20]; //packet body(example packet body) // Initialize packet body ...// Compose the packet headersendHdr.dest = slkSocketDLP;sendHdr.src = slkSocketDLP;sendHdr.type = slkPktTypeSystem;sendHdr.transId = 0; // let Serial Link Manager set the transId// Specify packet body writeList[0].size = sizeof(body); // first data block sizewriteList[0].dataP = body; // first data block pointerwriteList[1].size = 0; // no more data blocks // Send the packeterr = SlkSendPacket( &sendHdr, writeList ); ...}//// Example: Generating a new transaction ID given the previous // transaction ID. Can start with any seed value.//UInt8 NextTransactionID (UInt8 previousTransactionID){ UInt8 nextTransactionID; // Generate a new transaction id, avoid the // reserved values (0x00 and 0xFF) if ( previousTransactionID >= (UInt8)0xFE ) nextTransactionID = 1; // wrap around else nextTransactionID = previousTransactionID + 1; // increment return nextTransactionID;}
| Serial Driver Functions | Virtual Driver Functions |
|---|---|
|
DrvEntryPoint SdrvClose SdrvControl SdrvISP SdrvOpen SdrvReadChar SdrvStatus SdrvWriteChar |
DrvEntryPoint GetSize GetSpace VdrvControl VdrvOpen VdrvStatus VdrvWrite WriteBlock WriteByte |
| Connection Manager Functions | Serial Link Manager Functions |
|---|---|
|
CncAddProfile CncDeleteProfile CncGetProfileInfo CncGetProfileList |
SlkClose SlkCloseSocket SlkFlushSocket SlkOpen SlkOpenSocket SlkReceivePacket SlkSendPacket SlkSetSocketListener SlkSocketPortID |
|
|
|
|