Topic : TOS - das Betriebssystem Author : Version : tos.hyp (5. März 2013) Subject : Programmieren/Atari Nodes : 3001 Index Size : 93602 HCP-Version : 5 Compiled on : Atari @charset : atarist @lang : @default : Titel @help : @options : +g -i -s +x +zz -t4 @width : 70 View Ref-File15.10.4 Services TOS The services are not directly requested by the SRA, but determined by the Server, from the data identification provided by the SRA in messagebuf[4] when sending SSP_SRASR. ∙ SSP_SENDFILE - Send File Service Interactive IRS Used to make a networking application send a file to a destination (user). Upon sending of the SSP_SRASR message from the SRA to the Server, the shared memory block will contain a NULL-terminated filename for the file to be sent. dataID has to be SSP_FILENAME. The Server will request SSP_RECIPIENTS from the SPA with SSP_SSIR. The SPA then has to provide a shared memory block that contains a list of possible recipients separated by CRLF terminated by NULL with the SSP_SPASI message. The Server will open a list of the recipients for the user to choose from. The SPA will then receive a SSP_SSUR message containing the number of the recipient from the list in ssp_par1 (messagebuf[6]). The shared memory block will contain the NULL- terminated filename of the file to be sent. The SPA concludingly has to send SSP_SPASA to the Server, to close the session. The Server will send SSP_SSA to the SRA, indicating the service is in progress and the shared memory file can be closed and deleted by the SRA. Notes: Synchronization of the global contacts and the local contacts of the SPA can be done at this point. Folders: if a directory name instead of a filename is passed, the SPA should try to send the complete file folder, including all subdirectories and all files inside. ∙ SSP_STATUSDISPLAY - Status Display Service Invisible IRS Used to make any application (preferably those with permanent screen displays, for example TaskBar or MultiStrip or any Desktop) display status icons of other applications. Also see the Context Popup Service, which applications providing this service should implement to be able to request a popup menu in context to the current status from the SDS requesting app. Upon sending of the SSP_SRASR message, the SRA's shared memory block will contain icon data. A dataLen (messagebuf[2]/[3]) value of 0 (zero) removes the icon from the status display. This has to be done before exiting the SPA! dataID has to be SSP_STATUSICON. The Server will send SSP_SSIR with SSP_SDS as requestID, indicating use of the Status Display Service with the application id of the SRA in msgbuf[6] for distinguishing different SRAs on the SPAs side (e.g. to maintain consistent status icon positions in the display). SSP_SSIR will be sent to all registered SPAs providing this service, that are switched on for SDS by the user. If requestID (messagebuf[1]) is SSP_ENDSDS, the SPA has to remove the icon referring to the status of the application with the appl_id sent. The SPA will answer with SSP_SPASI without any further parameters. The Server will then send SSP_SSUR containing the application ID of the SRA in msgbuf[6]. The shared memory file will contain the icon data (16x16) to display. If requestID in SSP_SSIR was SSP_ENDSDS, the shm-block contains no data! The SPA has then to remove the status icon of the SRA. The SPA will answer with SSP_SPASA The Server will send SSP_SSA to the SRA, to indicate the status display has been updated, and the shm-file can be deleted. Notes: Upon registration of the SPAs with the Server, the Server will check if any not formerly registered apps providing the Status Display Service have registered. If so, a list of these SPAs will be presented to the user, with the possibility to turn the status display for single applications on and off. This makes it possible for the user to choose where the status icons are to be displayed. SPAs that are switched off for status display will not receive SSP_SSIR messages from the Server. ∙ SSP_DISPLAYMESSAGE - Display Message Service Invisible IRS Used to make an application display a text message from another application in one of their own windows. For example, messages received in iconified aICQ windows can be sent to be displayed in visible aIRC windows and vice versa. Upon sending of SSP_SRASR by the SRA, the shared memory block will contain the text to display. dataID has to be SSP_TEXT. The Server will send SSP_SSIR with the application ID of the SRA in msgbuf[6] to the SPA The SPA will answer with SSP_SPASI The Server will send SSP_SSUR containing the application ID of the SRA in msgbuf[6]. The shared memory block will contain the text to display. The SPA will display the text and answer with SSP_SPASA. It is up to the SPA to choose one or more of its windows to display the text in. The Server will send SSP_SSA to the SRA. Notes: Other than with the send message service, the text message is only to be displayed by the SPA, not sent over network connections to other users. ∙ SSP_SENDMESSAGE - Send Message Service Interactive IRS Used to make a (network) application post a message from another application in one of their own windows to a certain destination. For example, a text block selected in an editor can be sent to an online user in aICQ or to a channel or chat in aIRC, or as an email by any email client. Upon sending of SSP_SRASR by the SRA, the shared memory block will contain the text to post. dataID has to be SSP_TEXT. The Server will send SSP_SSIR requesting SSP_RECIPIENTS to the SPA. The SPA will answer with SSP_SPASI providing a list of possible destinations in shared memory (e.g. online users in aICQ or open channels/chats in aIRC) separated by CRLF terminated by NULL. The Server will open a list with possible destinations for the user to choose from. The SPA will then receive a SSP_SSUR message containing the number of the recipient from the list in ssp_par1 (messagebuf[6]). The shared memory block will contain a NULL- terminated string that is the message to send. The SPA will post the text to the chosen destination and answer with SSP_SPASA. The Server will send SSP_SSA to the SRA. Notes: Synchronization of global and local contacts can be done at this point. The Server might be able to determine if the recipients are email addresses (maybe by the SPAs registration information) and provide a possibility to type in a new recipient for the user. ∙ SSP_UPLOADFILE - Upload File Service Interactive IRS Used to make a networking application (ftp client or similar) upload a file to a destination (Server/directory). Upon sending of the SSP_SRASR message from the SRA to the Server, the shared memory block will contain a NULL-terminated filename for the file to be uploaded. dataID has to be SSP_FILENAME. The Server will request SSP_RECIPIENTS from the SPA with SSP_SSIR. The SPA then has to provide a shared memory block that contains a list of possible destination Servers (from the favorites) and a list of directories (from the favorites) with the SSP_SPASI message: server|user|pass|directory|directory[CRLF] server|user|pass|directory|directory|directory[CRLF] server|user|pass|directory[NULL] The Server will open a list of the destination Servers and directories for the user to choose from, and/or provide a text edit field for typing in Server, directory and login/password. The SPA will then receive a SSP_SSUR message, the shared memory block will contain the NULL-terminated filename of the file to be sent followed by the NULL-terminated Server name, NULL- terminated directory. The SPA concludingly has to send SSP_SPASA to the Server, to close the session. The Server will send SSP_SSA to the SRA, indicating the service is in progress and the shared memory file can be closed and deleted by the SRA. Notes: The ftp servers, directories and user/pass combinations will be held in global contacts as well, at some point. The SPA will still send the local favorites, and the global contacts can be synchronized with the local contacts by the Server at this point. Newly entered contacts can be integrated into the global contacts. Folders: if a directory name instead of a filename is passed, the SPA should try to upload the complete file folder, including all subdirectories and all files inside. ∙ SSP_COMPRESSFILE - Compress File Service Interactive DRS Used to make an archiver application compress a file Upon sending of the SSP_SRASR message from the SRA to the Server, the shared memory block will contain a NULL-terminated filename for the file to be compressed. dataID has to be SSP_FILENAME. The Server will request SSP_FORMATS from the SPA with SSP_SSIR. The SPA then has to provide a shared memory block that contains a list of possible compression formats (for TwoInOne e.g. LZH and ZIP, GuiTar TAR, GZ, TGZ) with a SSP_SPASI message. The Server will open a list of the formats for the user to choose from. The SPA can also provide one format in different versions, e.g. for compression levels ZIP low, medium and high compression. The SPA will then receive a SSP_SSUR message containing the number of the format from the list in ssp_par1 (messagebuf[6]). The shared memory block [shmID]_data.ssp will contain the NULL- terminated filename of the file to be sent. Additionally, the destination directory and filename for the archive will be provided in a shm-block with the name [archiver- appl_id]cmpname[sessionID].ssp, for example 25cmpname0.ssp, if the archiver has appl_id 25. After finishing (!!) compression of the file, the SPA will send SSP_SPASA. The Server will send SSP_SSA to the SRA, indicating the finished compression of the file. Notes: This service is a DRS, the acknowledge message is sent by the SPA after finished compression of the file. This is because this service can be combined with others (Send file or Upload file), so the archive file might have to be used for the second service. Folders: if a directory name instead of a filename is passed, the SPA should try to compress the complete file folder, including all subdirectories and all files inside, incorpoating the directory structure of the compression source into the compressed archive. ∙ SSP_CONTEXT - Context Popup Service Interactive IRS Used to make an app display a context menu in context of the current status displayed with the Status Display Service at a certain position on screen, and react on the user's choice from the popup. This service will be requested by the application that provides the Status Display Service! SPA will in this case also be SRA and SRA also SPA. Upon sending of the SSP_SRASR message from the SRA (the SDS providing application) to the Server, there will be no shared memory block. dataID has to be SSP_CONTEXT. messagebuf[6] and [7] have to contain the X- and Y-position of the mouse click, messagebuf[8] the mouse button vector as returned from evnt_button or evnt_multi. messagebuf[9] has to contain the application ID of the application that the status icon refers to. The appl_id for every icon is sent with the Status Display Service. dataID has to be SSP_CONTEXTREQUEST. The Server will request SSP_POPUP from the SPA with SSP_SSIR. The SPA has to answer with an SSP_SPASI message. No parameters (except requestID and sessionID) will be of any meaning in either of the messages. The SPA will then receive a SSP_SSUR message containing the X- position of the mouse click in messagebuf[6] and the Y-position in messagebuf[7]. Both coordinates are screen coordinates with 0/0 in the upper left corner. messagebuf[8] will contain the mouse button vector, stating which button(s) have been pressed, as usually returned by the AES evnt_xx functions. The SPA will then display its context popup, preferably in context to the current status displayed with the Status Display Service. After the user has chosen a popup entry, the SPA will send SSP_SPASA. The SRA (the Status Display Service providing application) will receive SSP_SSA. Notes: When receiving the SSP_SSIR message, the application providing the CPS (and hence requesting SDS) service, should open the context popup as quickly as possible, to provide responsivity and reasonable user feedback. The context popup should be in context to the current status display, for example if aICQs context popup is opened, one menu entry for connecting or disconnecting to an ICQ Server should be used, saying 'Connect' if aICQ is disconnected, and 'Disconnect' if it is already connected. Other possibilities would be to provide the other user status modes (Online, Invisible, Do not disturb, etc.) in the context popup for quick access, or an entry 'bring to top', that tops all aICQ windows. Since the context popup is actually displayed and handled by the application that uses the SDS, submenus and hierarchical popups are possible and encouraged. Try to keep it functional and easy to use, without overloading the context menus with options. The application does not need to be fully operateable only by the context menu, it's rather a way to make options that are status-dependent or are frequently used accessible quickly and easily. ∙ SSP_DISPLAYINFO - Display Information Service Interactive IRS Used to make an app send information (will mostly be used in context of the current status displayed with the Status Display Service) in the form of ASCII text. Can be used, for example, if a BubbleGEM event on a Status Icon occurs in TaskBar, to make the application requesting the status display send extended information about the current status for TaskBar to display. This service will probably most commonly be requested by the application that provides the Status Display Service! SPA will in this case also be SRA and SRA also SPA. Another possibility would be PS-Control-like applications, that show system information about running processes (CPU and memory usage, etc.). These could then also display information about the application's current status. N.AES could use this service to display the current status of the applications when switching apps with [Alternate]+[Tab]. Upon sending of the SSP_SRASR message from the SRA (the SDS providing application) to the Server, the shared memory block has to be a buffer with space for the maximum size of displayable information and read and write access rights. dataID has to be SSP_INFOBUF. The Server will request SSP_INFO from the SPA with SSP_SSIR. The SPA is to prepare the information to display (consider current status). The SPA has to answer with an SSP_SPASI message. No params (except requestID, sessionID) have any meaning. The SPA will then receive a SSP_SSUR message. messagebuf[7] will contain the maximum length of information. The SPA is then to copy the information to display into the existing shared memory block provided with SSP_SSIR. The SPA doesn't need to create its own shm-block. The SPA will send SSP_SPASA after copying the string to shm and freeing temporary memory. The SRA (e.g. the Status Display Service providing application) will receive SSP_SSA. This indicates that the information is now in the shared memory file provided at SSP_SRASR and can be displayed, and the shm-file deleted. Notes: Careful with the shared memory on this one! The SRA has to create the shared memory file as read/write! Otherwise the SPA might not be able to copy the information text to it, if the operating system supports access rights for shared memory! Delays for the information display (e.g. showing the display after the mouse has been over the status icon for more than 2 seconds or so) will be handled by the SRA. The information display should be in context to the current status display, for example displaying the current user status mode (Online, Invisible, Do not disturb, etc.) Only display vital information, try not to overload the bubble. Use the information to display more details about what the current status icon means, things like that.