@database El-CID.guide @author "Peter Bornhall" @$VER: El-CID.guide 2.0 (9.5.96) @node main "El-CID Documentation" Leading Amiga Software presents El-CID -- CallerID the easy way ================================= Copyright ©1996, Peter Bornhall All rights reserved. @{" Description " link Description} @{" Legal Information " link Legal} @{" Requirements " link Requirements} @{" Features " link Features} @{" Installation " link Installation} @{" Configuration " link Configuration} @{" Starting El-CID " link Starting} @{" Stopping El-CID " link Stopping} @{" History " link History 9999} @{" Future " link Future} @{" Bugs " link Bugs} @{" Author " link Author} @{" Acknowledgements " link Acknowledgements} @endnode @node Description "Description of El-CID, and what it could do for you" @{b}Description@{ub} El-CID is a small program which enables you to make use of the CallerID function built into your modem. If your modem supports this function, and it's properly set up, El-CID will notify you of any incoming calls directly on your screen. El-CID also pops up on the frontmost public screen, so there is no need to flip screens to see who is calling. El-CID has so far been verified to work with the following modem(s); * PowerBit 28k8 Lite (aka InterTex) If the make and model of your modem isn't listed here, and you know for sure that it has CallerID support, please drop me a line and tell me if you got El-CID working with it or not, and what settings to use. @endnode @node Legal "If you fall and break a leg, don't blame me!" @{b}Copyright@{ub} El-CID and all other files included in the original distribution is Copyright ©1996, Peter Bornhall. @{b}Distribution license@{ub} El-CID is released under the concept of giftware. This means that you should send a suitable gift to the author if you continue to frequently use this software. If you are unable to find a suitable gift, you are welcome to send a small donation in any currency. You may freely copy this software, as long as the following requirements are fulfilled: * All files are copied without any alterations/modifications. If any extra files are added, it must be obvious that they don't belong to the original distribution, and that they don't need to be included in any redistribution. * The copying is done on a non-commercial basis. A small fee to cover media costs may be charged. Selling this software is strictly prohibited. * The copier isn't claiming the copyright of this program. Any exceptions from the above requires a written permission from the author. If you want to publish this program on a cover disk or similar, contact me first for approval (to make sure you have the latest version etc). I then expect a copy of the issue in question as license fee. @{b}Warranty@{ub} THERE IS NO WARRANTY FOR THIS PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS WITH YOU. SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAMS TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. @endnode @node Requirements "Requirements? For such a small program?" @{b}Requirements@{ub} El-CID should work on all Amigas equipped with at least OS 2.04, but it also makes use of some new features present only in OS 3.0 and higher. El-CID uses about 56KB of memory when no phonebook is loaded. This does not take into account if bgui.library is loaded into memory or not. El-CID requires the following for proper operation; * A modem that has a built-in CallerID function. * The bgui.library in LIBS:, version 38 or higher. El-CID uses the excellent OwnDevUnit.library if it is present. That means that you do not have to quit El-CID when another program needs the device currently in use by El-CID. This does however require the other program to use OwnDevUnit.library too. @endnode @node Features "The much sought-after features of El-CID" @{b}Features@{ub} Most of the following features are things I wanted myself, but I do hope that they appeal to you too. * Uses new features of OS 2.1, OS 3.0 or higher. * It is a commodity, and can be enabled/disabled at any time. * It uses BGUI.library for its GUI and commodity interface. * Uses OwnDevUnit.library if available. * It pops up on the frontmost public screen. * Displays the date and time in localized form. OS 2.1+ * User may specify device and unit to use. * Simple phonebook, displaying the name of the caller. * Simple call logging, with date, time and caller. @endnode @node Installation "Installing El-CID on your system" @{b}Installation@{ub} You may put El-CID wherever you want to, but I recommend that you put it in your WBStartup drawer, which will start it every time you boot up your Workbench. For further information, see the section on @{" configuration " link Configuration}. @endnode @node Configuration "How do I set it up?" @{b}Configuration@{ub} There are three major areas to deal with when configuring El-CID; * @{" Tooltypes " link Tooltypes} The basic settings. * @{" Phonebook " link Phonebook} How to create a phonebook. * @{" The modem " link Modem} How to set up the modem. @endnode @node Starting "Starting it up" @{b}Starting El-CID@{ub} El-CID is best started from its icon, since it relies on tooltypes for all configuration. If there is demand for it, I might consider adding support for CLI/Shell arguments, but until then you will have to make If you decide to start it from Shell/CLI, you have to run it, i.e; Run NIL: El-CID ...if you want your prompt back. El-CID will not start more than once, and attempting to run a second copy causes the first copy to show its interface. This is standard commodity behaviour. But, since it is possible to specify the device and unit that El-CID uses, I might change this behaviour if there is a demand for it. @endnode @node Stopping "Stopping it, should you want to" @{b}Stopping El-CID@{ub} You may easily remove El-CID from your system in several ways; * Pop up El-CID's interface and select 'Quit' from the menu. * Use the Exchange commodity to remove it. * Send it a CTRL-C break command. @endnode @node Tooltypes "Don't you just loooove configurability!" @{b}Tooltypes@{ub} El-CID uses the tooltypes of its icon to set the parameters it uses. This means that it is easily accessible from Workbench, by selecting Information in the Icons menu. You may also use project icons to start El-CID. Just set default tool to El-CID, and edit the tooltypes to your preferences. Here follows a brief description of every tooltype; CX_POPUP= This tooltype specifies if El-CID should open its window directly on startup. El-CID responds to YES and TRUE, and defaults to not open the window on startup. Example: CX_POPUP=YES CX_POPKEY= With this tooltype you can specify the popup qualifier and key. The default is ctrl, left alt and 'e' ('ctrl lalt e'). Example: CX_POPKEY=ralt e DETECT= With this tooltype you can specify the detection string used to find the number of the caller. Use this with care, since El-CID will NOT work if this isn't properly specified. Check your modem's User's Manual to find out which output is produced (formatted output works best). Default is 'NMBR = '. Example: DETECT=NMBR= See also: @{"Setting up the modem" link Modem} DEVICE_NAME= With this tooltype you can specify which device you want El-CID to use. Default device is serial.device. Example: DEVICE_NAME=8n1.device DEVICE_UNIT= With this tooltype you can specify which unit El-CID should try to gain access to. Default unit is 0. Example: DEVICE_UNIT=4 PHONEBOOK= With this tooltype you can specify the path and filename of the phonebook El-CID should use. If El-CID fails to open it, you will NOT be notified, and no phonebook will be loaded. Default is S:El-CID.phonebook. Example: PHONEBOOK=SYS:Tools/El-CID.numbers LOGFILE= With this tooltype you can specify the path and filename of the logfile El-CID should write to. Be careful with this, as you might overwrite important data if you don't know what you're doing. The default is S:El-CID.logfile. Example: LOGFILE=LOGS:El-CID.log ACTIVATE If this tooltype is present, El-CID will make the message window activated when it opens. Default is not to ACTIVATE. Example: ACTIVATE NORESIZE With this tooltype you can tell El-CID not to let you resize the message window horizontally. Since the message window reopens whenever a new call is detected, it is automatically resized, so you might want to set this flag. Default is to let you resize the window. Example: NORESIZE TOOLTICKS= With this tooltype you can specify the delay in intuiticks (about 10 per second) for tooltips to appear. Setting this to 0 disables tooltips completely. Default setting is 0. Example: TOOLTICKS=20 WINDOW_DELAY= With this tooltype you can specify how long the message window will be shown when it is popped up. If you have selected the 'Show Interface' button from Exchange, the window will ALWAYS be shown, until you manually close it. Setting this to 0 causes El-CID to never open the message window, unless manually opened with the hotkey or via Exchange. Default is 10 seconds. Example: WINDOW_DELAY=15 REOWN_DELAY= With this tooltype you can specify the delaytime used between releasing the device and trying to reown it. Minimum value is 5 seconds, and the default is 6 seconds. Example: REOWN_DELAY=8 POLL_DELAY= With this tooltype you can specify how often El-CID should check if the device is available to use. Minimum and default value is 1 second. Example: POLL_DELAY=3 WAIT_DELAY= This tooltype specifies the delay used by El-CID to make sure that we really got a connection with the modem. This is needed in some cases when El-CID reclaims the device from some other program and the modem isn't finished talking with the other end. Minimum and default value is 10 seconds. Example: WAIT_DELAY=15 @endnode @node Phonebook "Let's see, how many friends have I got?" @{b}Phonebook@{ub} El-CID sports a simple phonebook, and is able to display the name of the caller if the number is present in the phonebook. The phonebook is a plain ASCII text file, and each row in it consists of a number and a name (or whatever you like). If the incoming number is present in the phonebook, it will be displayed in the message window like this; "Incoming call from Peter Bornhall..." In a future version I might make it possible to specify the format of this string, making it possible to have "Peter Bornhall is calling..." instead. Each line in the phonebook file is one entry, and each entry is formatted like this; :[!] ...where is the number that El-CID displays in its number box. You must separate the number from the rest of the line with a colon, or it won't be recognized by El-CID. The [!] means that if the first character following the colon is an exclamation mark, the will be displayed in the number box instead of in the status box. Example: B00:!Unknown B10:!Protected 0123456789:John Doe 9876543210:Jane Doe The first two entries are used by Telia in Sweden as codes for calls without CID information (B00), or protected calls (B10). If one of these two are detected, El-CID will display "Unknown" or "Protected" respectively in the number box. Otherwise, as with the two latter entries, the number will be shown in the number box, and the name in the status box. @endnode @node Modem "Setting up your modem to work with El-CID" @{b}Modem Setup@{ub} The first thing you should do, is to make sure that your modem is able to detect CallerID information. You should be able to find the information you need in the user manual for your modem. Then, you must set the modem to always display the CallerID information when it is received. In most cases formatted output is the best choice, since it usually contains more strings that can be used to detect the relevant info, the incoming caller's number. For example, the formatted output of a PowerBit 28k8 Lite modem, setup with AT#CID=1, looks like this; RING DATE = 0000 TIME = 0000 NMBR = 123456789 RING What we are interested in here, is the line containing the number. In this case, the detection string (minus the quotes) is "NMBR = ". Please note that we must use the EXACT string sent from the modem, and we must also use all characters up to the first digit of the number. On the other hand, using a detection string of "BR = " would work just as well. Finally, when you have found out what detection string to use, make sure that you save the modem's settings, so that it automatically receives CallerID information when it is reset with ATZ. This is required, since El-CID only sends "ATZ" to reset the modem, nothing else. @endnode @node History "History, for what it's worth" @{b}History@{ub} Since this is my first project, I guess this part will be quite big in a short time. Bear with me, it's a learning project. --.- 1.3.96 [INTERNAL Release 0.1] * First version, internal use only. Actually works. 37.1 2.3.96 * Rearranged the sourcecode a bit, since it was a real mess to work with. Resides in its own directory now...:) Oh, and I added revision control to it also. 37.2 3.3.96 * Rearranged the source some more, removed some unnecessary includes, made a proper smakefile and recompiled. No major changes made from 37.1. 37.3 3.3.96 [INTERNAL Release 0.2] * Added a one-second delay between checks for re-obtaining the device from OwnDevUnit. Sucked CPU time like a vacuum cleaner before. Quite horrible... 37.4 4.3.96 * Split up the code a bit, preparing it for the new features and problem fixes. Also decreased the size quite a bit. 37.5 5.3.96 * Rewrote the entire event handler, and added timer.device code, making it possible to operate El-CID even while the device is released to some other program. No new features in this version, but I added some support for easy adapting it to let the user set some parameters. * Changed the message window delay to 10 seconds. 37.6 5.3.96 * Tweaked the message window a bit. * Fixed a minor bug that left the 'Incoming call detected...' message hanging in the status box forever. Now resets after the message window delay time, 10 seconds. 37.7 6.3.96 [BETA Release 0.3] * Scraped off 172 bytes from the executable...:) 37.8 6.3.96 * Added tooltype support routines. * Added ability to specify device and unit number using the newly added tooltypes. Currently only available from Workbench, no Shell/CLI support yet. * Now possible to set the Message Window delay, as well as the Reown and Poll delay. See @{" tooltypes " link Tooltypes}. * Created an icon for El-CID. Uses the same style as my Iconite icon "package" (can be found on AmiNet). Yes, I know, it doesn't look good with MagicWB's palette...:) 37.9 7.3.96 * Added menus to the message window. You can now use the menus (or the menu shortcuts) to select Hide, Quit and About... Hide closes the message window, Quit quits El-CID completely, and About... shows a small about requester. Your basic commodity stuff, more or less. 37.10 7.3.96 * Added simple phonebook support. See @{" phonebook " link Phonebook} section for more information on this. 37.11 7.3.96 * Added menus to update (free and reload) the phonebook, as well as to simply flush it (free only). 37.12 8.3.96 * Added simple call logging to El-CID. Currently only a hardcoded filename ("S:El-CID.logfile"), but this is supposed to be changed. * Added hotkey support. Currently hardcoded as . * Locale-formatted (if available) date and time strings in the message window and log file. El-CID falls back to AmigaDOS formatted date and time if locale can't be opened as it should. 37.13 10.3.96 [BETA Release 0.4] * Added tooltype support for specifying the phonebook and logfile, as well as an option to prevent resizing the message window. Also added tooltype to set the tooltip delay time. * It is now possible to specify the detection sequence used for detecting the number of the caller. If you take a look in your modem's User's Manual, you will most likely find out what the formatted output looks like. Default is as before 'NMBR = '. * Message window is now always reopened when a call is detected. For two reasons; first, the window can now always pop to the front screen, and second, you will always be able to see the entire date and time of the call. With certain fonts and locale settings you might otherwise lose part of the date string or similar. * Now possible to specify the popup key using CX_POPKEY. 37.14 11.3.96 * Removed the spaces around the date and time strings, and changed the way El-CID writes to the log file. It will now write the entire line at once, instead of writing the different parts of the line one by one. 37.15 15.3.96 [INTERNAL Release 0.5] * El-CID now resets the modem after it receives the CallerID-sequence. Hopefully this will solve the problem with not receiving all calls, since I think this was the reason for that problem. * Window title now reads "El-CID: Hot Key = ", making it similar in appearance to other commoditys. 37.16 2.5.96 [PUBLIC Release 1.0] * I finally managed to track down the reason to why El-CID failed to detect some calls. And it wasn't even El-CID's fault in the first place! I found that TrapDoor seems to leave the serial.device (or whatever you use) in a state that prevented El-CID from detecting the calls. Phew! 37.17 4.5.96 * Added the WindowToFront capability to the hotkey. The window will now always pop to front when you activate the hotkey combination. * Added the CX_POPUP tooltype. Works same way as CX_POPUP normally does, of course. * Changed the About window a bit to more accurately reflect the nature of El-CID's function. * El-CID no longer attempts to own and open the device before attempting to create the CX broker. Before, the second El-CID started made the first one close the device, and relinquish control to the second, which then quit (since the broker already existed) and gave control back to the first El-CID. 37.18 6.5.96 * Found and fixed a bug that caused El-CID to always think that the detection string was 7 characters in length. Sorry about that. 37.19 7.5.96 [INTERNAL Release 1.1] * Figured out a way to (hopefully) circumvent the problem I've had with TrapDoor. It seems to work in my test code, but the implementation in 37.19 is too buggy to work as it should. * Still trying to get 37.19 to work, but to no avail. I am however in the process of rewriting the whole interface to the device, and my bare-bones program for this seems to work with none of the problems found in versions <= 37.19. Next version will be a mostly rewritten program, apart from stuff like the phonebook, which works perfectly. 37.20 9.5.96 [INTERNAL Release 2.0 BETA] * Almost all code is now rewritten from scratch, and as a result, it is a lot more stable. * OwnDevUnit.library is now optional, and is used automatically if it is installed. * El-CID should now handle deadlocks better, since I now do a reset after WAIT_DELAY seconds after the device is first reclaimed from the previous owner. IF there is serial activity before this delay has expired, the reset is never performed, since it seems to work anyway. This solution seems to work perfectly here at least. * Now uses memory pools on OS 3.0 and higher. * Default hotkey is now "ctrl lalt e", since the old hotkey, "lalt e", conflicted with the "©" character. 37.21 9.5.96 [PUBLIC Release 2.0] * WINDOW_DELAY=0 will now prevent El-CID from opening its message window when a call is detected. * Now requires bgui.library version 39 or higher, which is the currently available version on AmiNet. * Implemented the ACTIVATE tooltype, which prevents El-CID from making the message window active when it opens. @endnode @node Future "Future? You surely must be kidding?" @{b}Future@{ub} I plan on some additional features for El-CID; * Additional tooltypes. * Userdefinable strings. * Localization even? * Better error detection. * Shared mode (not sure if this is possible). * Ability to view the last calls from El-CID. * Phonebook editor maybe? * Suggestions? @endnode @node Bugs "Nasty little critters, aren't they?" @{b}Bugs@{ub} No actual bugs known at this time. Any bugs and/or problems you may encounter should be reported to me as soon as humanly possible. Also remember that I take NO responsibility for YOUR mistakes. Some things I'm aware of (if they could be called bugs); * Device name, phonebook and log filename are limited to a length of 255 chars. Same thing applies to the line length of the phonebook. * No sanity checks for the log and phonebook filenames are performed, so if YOU enter strange things for these things, expect the worst...:) I will probably try to correct some of the above mentioned "flaws" if or when I get the time and motivation. @endnode @node Author "Me, me, me... That's all I ever think about" @{b}The Author@{ub} Contact me for any reason, at; Snail: Peter Bornhall Bäck 5, Främmestad S-46598 NOSSEBRO SWEDEN FidoNet: 2:201/417.41 InfoNet: 42:105/106.41 or 42:106/106.41 e-mail: bornhall@karkis.canit.se homepage: http://www.geocities.com/siliconvalley/5948 IRC: Bornhall on #AmigaCafe (undernet) @endnode @node Acknowledgements "Who did all the HARD work then?" @{b}Acknowledgements@{ub} Some words of thanks must go to; * Marcus Ohlström, for leading me on the right track regarding the serial routines. Thanks, mate! * Ian J. Einman, for taking over development of the still excellent BGUI library. I for one will continue using it! * Jan van den Baard, for the simply excellent BGUI library. It makes life as a programmer a whole lot easier! * Christopher A. Wichura, for making OwnDevUnit.library. * Olaf Barthel, for releasing the source for term. It's been a veritable fountain of knowledge, hints and tips, and I don't think El-CID would be where it is today, hadn't it been for this. * Swedish telecom company Telia, for FINALLY getting AXE in my part of Sweden. You promised it six months ago, you buggers. @endnode