Sparrow Frequently Asked Questions Q: Which binary file do I install for my device? A: RIM 950 OS (950 device) sparrow.dll RIM 950 OS 1.7 (950 device) sparrow17.dll RIM 850 OS 1.6 (850 device) sparrow16.dll Blackberry OS 1.5 (older 950 device) sparrow15.dll Blackberry OS 2.0/2.1 (850, 950, 957 devices) sparrow20.dll Q: What is Sparrow? What is a Blackberry? A: The RIM devices (850, 950, 957) have a great capability; flat-rate priced messaging and enough storage to hold hundreds of messages. Unfortunately the built-in mail application is missing some features, and without them it makes using it harder than it needs to be. http://www.rim.net http://www.blackberry.net Sparrow duplicates most of the capability of the built-in mail application, it is a separate application which had to be written from scratch. Therefore it may be missing some intricate or proprietary feature of the built-in mail application until such feature can be implemented. Sparrow is a work in progress, but being that it is a free and open project I thought it best to release it once it became useful to me. Q: What extra features does Sparrow give you? A: User-defined folders with rules for matching. Each folder has independent alert settings, and shows the message read/unread counts next to the folder name. This allows mail to be organized in a similar manner as a desktop mail system. A mail relay option which lets you use custom headers. This allows your outgoing mail to be sent to an email account for further processing. An RFC822 compliant header is added at the top of the message body which is then used to process the mail during the relay. Use of procmail is recommended. Navigation is improved; alt-roll & enter (alt-enter) is page scrolling, space key jumps to the next paragraph, 't' (top) 'b' (bottom) 'n' (next) 'p' (previous) 'g' (up 1 line) 'v' (down 1 line) quick navigation keys. Delete lines with cap-backspace. Both top and bottom methods of quoting for replies. There is also a channel mode. You can view a folder as a set of continuous (auto-scrolling) text which allows you to use services such as trancell's IRC more smoothly. Q: What is the syntax for folder rules? A: A rule is just a substring which is compared against From, To/Cc, and Subject of all messages. Only the email portion is matched against. It is currently case-sensitive and multiple rules are ORed together, meaning that any matching rule will include the message. In Sparrow the messages are never physically moved into different folders, the folders are just different views of the same database so you may change them at any time. The INBOX actually ignores any rules assigned to it, and it is hard-coded to include only the messages which don't match other folders. Yes, I do plan on fixing little things like that; i.e. don't have the "new rule" option for the INBOX folder since it is ignored. The code for rule matching is in folder.cpp, FolderRecord::match(...) Q: Why was making Sparrow more difficult than writing a normal application? A: Well.. Though it may seem like a simple thing, getting full access to the messaging database is plagued with specific problems. The built-in mail application must be notified of any changes that Sparrow makes to the database and vice versa. And it must do so in a controlled manner so that database views are synchronized and do not reference invalid records. Unfortunately the Messaging API gives only a limited interface to the messaging database and is insufficient to write a mail replacement. We have succeeded only through perseverence, luck, and a moderate level of code disassembly to achieve the necessary API. Q: Why is Sparrow so complicated, i.e. mail relay, channel mode, etc? A: It's not my fault! I am not a feature creeper; I merely added features which *I* wanted as I was going along. The mail relay is probably the most obtuse feature and its only purpose is to fix a rather lame "feature" of the RIM backend. Without the mail relay option, all of your outgoing mail will be From: your pager's email address.. thereby allowing spammers to use your pager as a trash receptacle. By using Sparrow's mail relay option your mail will be redirected to another of your accounts so that you may adjust the headers. For example, here is my procmail recipe: # Discard loops :0 * ^X-Loop: Sparrow loop /dev/null # Here is where I forward Sparrow mails. # Sparrow is my RIM application; # http://rallypilot.sourceforge.net/bb/index.html :0 * ^From:.*myaccount@gomail\.net * ^Subject: Sparrow: msg to forward { :0 ciwb | formail -A "X-Loop: Sparrow loop" \ | sendmail -oi -t :0 # send a copy home for my records ! myhome_email_address } All it does is remove the topmost RFC822 header (i.e. ciwb does not have an h), adds an X-Loop for protection, and then sends the message body (with my RFC822 header on top) into sendmail. Q: How to I compile Sparrow? A: I use MS VC++ 6.0, but I believe most versions will work. You'll need to get the appropriate SDKs from RIM depending on which pager binaries you want to build. There are 5 projects (.dsp files) within Sparrow which correspond to the different SDKs needed. My SDKs are installed thusly: RIM 950 OS c:\rim RIM 950 OS 1.7 c:\rim17 RIM 850 OS 1.6 c:\bb16 Blackberry 1.5 c:\bb15 Blackberry 2.0 c:\bb20 So in the sparrow20.dsp file for example (you can use a text editor) you will want to either search/replace those directory references to your equivalents or you could install yours in the same places as mine. When you are in Visual Studio you'll want to open the sparrow.dsw workspace and make sure you select the proper project. It is selected via Build - Set Active Configuration. I also have batch files which build using the various makefiles. I have my VC++ set to always create these makefiles. When I want to build a release binary, I just run release.bat or release20.bat etc. Q: How does the HEADLINES folder work? A: Here is just a brief explanation. On the Internet there are many thousands of RSS/RDF formatted headlines. This is a well-known XML format which is used to show the little headlines you see in columns within web browsers. Sparrow has an XML parser which recognizes RSS/RDF in a message body and sticks it in the spXML database, which the HEADLINES folder allows you to view. There is a size issue unfortunately. Over the years, the RSS/RDF files have become bloated and many are in excess of the 2k limit of Blackberry messages. Since there is no facility in Sparrow for auto-requesting "more" of a message, you will be limited to 2k on those devices. The IPS and IPS Plus have a limit of 16k which is plenty. Although I find that most headline files are too redundant to include in their entirety anyhow, and so I will probably crop mine down to less that 2k just for efficiency on my IPS device. Here is an example script to grab headlines from a few sites: #!/bin/sh fetch() { wget -q -N -T10 -O $1.rss.tmp \ "http://p.moreover.com/cgi-local/page?c=$1&o=rss" if [ $? -eq 0 ]; then diff -q $1.rss $1.rss.tmp if [ $? -ne 0 ]; then rm -f $1.rss mv $1.rss.tmp $1.rss cat $1.rss | \ formail -A "From: myhome_email_address" \ -A "To: myhome_pager_address" \ -A "Subject: Headlines - $1" | \ head -c 15800 | \ sendmail -oi -t else rm -f $1.rss.tmp fi fi } fetch_url() { wget -q -N -T10 -O $1.rss.tmp "$2" if [ $? -eq 0 ]; then diff -q $1.rss $1.rss.tmp if [ $? -ne 0 ]; then rm -f $1.rss mv $1.rss.tmp $1.rss cat $1.rss | \ formail -A "From: myhome_email_address" \ -A "To: myhome_pager_address" \ -A "Subject: Headlines - $1" | \ head -c 15800 | \ sendmail -oi -t else rm -f $1.rss.tmp fi fi } cd ~/headlines if [ $? != 0 ]; then exit; fi # These are from www.moreover.com fetch "IPO+news" fetch "Developer+news" fetch "Linux+news" fetch "Wireless+sector+news" fetch "Handhelds+news" fetch "Open+source+news" fetch "Top+stories" # These are tech from all over the place fetch_url "debianhelp" "http://www.debianhelp.org/backend.php" fetch_url "slashdot" "http://slashdot.org/slashdot.rdf" fetch_url "pdabuzz" "http://www.pdabuzz.com/netscape.txt" fetch_url "linuxtoday" "http://www.linuxtoday.com/backend/my-netscape.rdf" fetch_url "linuxnewbie" "http://www.linuxnewbie.org/news.cdf" fetch_url "drdobbs" "http://www.technetcast.com/tnc_headlines.rdf" fetch_url "palmstation" "http://www.palmstation.com/palmstation.rdf" fetch_url "wirednews" "http://www.wired.com/news_drop/netcenter/netcenter.rdf" fetch_url "osopinion" "http://www.osopinion.com/OSOlinks2.xml" fetch_url "salon" "http://www.salon.com/feed/RDF/salon_use.rdf" # Stocks #fetch_url "stockwisdom" "http://www.stockwisdom.com/netscapechannel.asp" fetch_url "motleyfool" "http://www.fool.com/about/headlines/rss_headlines.asp"