However, I recently found some annoying problems of KVO while building some reusable programming components ^(I’ll open source as much as possible when ready.)$ for Voodo and future iOS projects.

Observers can not be queried

Observers are stored in dictionaries ^(See NSKeyValueObserving protocol’s observationInfo.)$, so it should be very easy to query whether an object A is a registered observer of object B. But one can’t do that.

Unregistering an unregistered observer throws exception

One can not query whether A is an observer of B in the first place, and can neither try to unregister it from B when one wants to ensure that A is unregistered from B. It is just ridiculous! And why is removing a nonexistent observer so fatal while removing a nonexistent entry from a collection is reasonably ignored? ^(See NSMutableArray’s removeObject: and NSMutableDictionary’s removeObjectForKey:)$

Observers/observees don’t auto-dissolve the KVO relationship in dealloc

It can be easily done in KVO framework code since it already has the data structure keeping the observer-observee relationship information, and is very reasonable things to do – when any part of a relationship is gone the relationship is ended. Without the auto-unregistration, developers’ responsibility is unnecessarily heavier. In fact, it is no easy work in cases where observers outlive observees, because an observee needs to notify its observers of its death so the observers can detach themselves from the dying observee. ^(Normally it is the observers that are doing the KVO relationship management and it is the job of whoever did the connection to do the disconnection, but vice versa)$

All in all

KVO leaves some extra, tedious, and burdensome relationship management work to us while it could be easily and efficiently done at the root of itself. ^(Well, as Appler eskimo1 said in devforums, it is harder than one might think because KVO needs to be both thread safe and GC clean, and must be careful to not impact the performance of code that isn’t using it.)$

The KVO relationship management is especially stressful for observers watching many dynamic observees which is not unusual for generic components – UINavigationController and UITabBarController both manage a dynamic group of UIViewControllers and may observe some properties of them. It is even worse in my component because not only the observee but also the observed properties of them are dynamic. May Apple save me (and you?).

Apple taught me most I need to know about how to manage the interface orientation, but still left some dark corners that I had to explore by myself. Now that I’ve seen the whole landscape, I want to share it with you.

Read the documentation first if you haven’t yet. After that, you should know how to write the rotation code to respond to orientation changes, if only you are notified of the orientation changes in the first place.

Your view controller is always notified of the orientation changes if it is the frontmost view controller – the only view controller, the top modal view controller, the top view controller in the top navigation controller, or the current selected view controller in top tab bar controller. In these cases, simply following the documentation by implementing your rotation logic in those view rotation methods ^(willRotateToInterfaceOrientation:duration:, willAnimateRotationToInterfaceOrientation:duration:, and didRotateFromInterfaceOrientation:)$ is enough.

However, no view rotation message will be sent to your view controller if the rotation occurs when it is not in the frontmost. Well, it is very reasonable behavior though, since its view is invisible then. Laziness is a great virtue here. What’s the point of rotating the invisible view under the hood except for consuming more battery, especially considering that the interface may be rotated back to its original orientation? What makes it a problem is the fact that these messages will neither be sent to your view controller when it becomes the frontmost one later. Your view controller will be never aware of the orientation changes that happen when it is not in the frontmost! One example for better understanding:

1. A is the current selected view controller in a tab bar controller and the device is in portrait orientation.
2. View controller B is selected in the tab bar controller.
3. The device is rotated to landscape orientation.
4. A is selected again.

See the problem? The orientation is portrait at first, and view controller A presents its view correctly; the orientation becomes landscape later, but A does not know that and still presents a portrait view when it returns to the frontmost.

In fact, the example could be reduced to a simpler one:

1. B is the current selected view controller in a tab bar controller and the device is in portrait orientation.
2. The device is rotated to landscape orientation.
3. View controller A is selected.

The example can be easily extended to view controllers managed by a navigation controller. ^(The situation of modal view controllers is different. The rotation messages will be properly sent to the concerning view controllers. I don’t know why Apple can’t treat them the same way.)$ The problem is reduced to: view controller A initially sets up its view in portrait mode and relies on the code in view rotation methods to adjust the view to new orientations, but view rotation messages are never sent to A so it never rotates its view.

It is clear now that not only view rotation methods should have code for adjusting view for different orientations, but also the initial view setting up code should be orientation dependent. And that’s Apple didn’t tell us.

Finally, here is my way to attack this problem:

• Factor the orientation-dependent layout code into a method, naturally called (void)layoutView:(UIInterfaceOrientation)orientation.
• Call layoutView: in both viewWillAppear: and willAnimateRotationToInterfaceOrientation:duration:.

May this article help you rotate your apps nicely and may your apps rock.

HeaderDoc is obviously not favored by developers. Doxygen is better and even officially advocated by Apple, but still tedious to use and just can’t generate Apple standard documentations(see a nice example here). Doxyclean is very helpful in converting Doxygen output to resemble Apple Developer Documentation, but seems not capable to generate Xcode Documentation Sets. Following the work of Doxyclean, appledoc supplements some missing features like Xcode Documentation Set generation.

To sum up, there are several third-party tools doing the work that should be better done by Apple in Apple way. Even though they can do their best to generate very Apple like documentations, they can not offer the smooth integration in Xcode that is otherwise possible if it is done by Apple.

So, I’ve posted a bug report(Problem ID: 8193210) to request such a Documentation Set generation tool. If you also want it, please go to duplicate a bug report with following content:

I vote for bug report ‘8193210′.

Summary:
Documentation set generation tool in Xcode to generate documentation set in the style of Apple Developer Documentation is necessary for a prosperous Apple developer community. The current HeaderDoc and doxygen are both far from the Apple standard.

Steps to Reproduce:

Expected Results:

Actual Results:

Regression:

Notes:

Read this article to learn why and how to vote for a bug report. ^(Surely I’ve voted this “international promo codes” bug report since I’m from China.)$

对 app 自身的截图，用真机 + Xcode 就能完美解决，但是对截图做注释就需额外的工具来完成。

一说到对图片进行操作，大家容易先想到 Photoshop, Illustrator，OmniGraffle 等重器，轻一点的也是 Acorn，Pixelmator 等。

这些专业的图片编辑软件确实强大，有些功能只有它们能提供。比如，我试了一圈，最终发现还是 Illustrator 里的 gradient 强大，是唯一一个直接支持 ellipse gradient 效果的，于是在对截图做聚光效果时都是用的 Illustrator。

既然我在对 Voodo 2 做截图时用的是 Xcode，后续工作是图片注释，为什么还需要截屏软件呢？

这是因为，其实大多截屏软件都自带注释功能，足以应付绝大多数需求；而且因为 Voodo 有同步 Google Calendar 的功能，我需要对 Google Calendar 上的操作进行一些截图。

下面就我用过的一些截屏软件做一个简单的比较（排名无明显先后）：

Snagit

Snagit 不愧是老牌领头羊，beta 就已经多方面超越其他先入场的小弟了，操作的灵活性，注释工具都是最好的。beta 版免费使用，很爽。

没有单独的 Full Screen Capture，那是因为根本不需要，人家的 All-in-One Capture 太帅了，自动识别 Full Screen，Window，甚至 Region in Window，还有 Capture Scrolling Area 能对需要滚动才能看全的页面做完整的截图。

Share 功能尚未成型，暂时只内嵌了 Email 功能。相信正式版肯定会有完善的 Share 功能，看看 TechSmith 的其他软件就知道了，何况人家还拥有自己的专业多媒体资源分享网站 Screencast.com。

Snapz Pro X

Snapz Pro X 没有注释功能，也不带 Share。但就截图的一个“截”字来说，Snapz Pro X 确实可算是最强悍的，算是名副其实。看一个它特有的截图功能：

其实把它放到这里并不完全合适，因为 Snapz Pro X 同时还是强大的 Screencast 录制软件。我购买它就是为了给 Voodo 录制 demo 及 promo video，配合着 iMovie 做的后期制作，一般的效果都能达到。

Skitch

Skitch 的 UI 设计相当独特，类似一个相框，上传分享特别方便（skitch.com，flickr，Mobile Me 等一应俱全），截图质量和注释工具都不错，而且免费。性价比最高，估计是目前最普及的截图软件。我一般都通过 Skitch 上传到 skitch.com 秀图给别人看。

LittleSnapper

LittleSnapper 可能是最眼熟的一个名字。软件本身 UI 也算清爽，功能也算齐全，支持多种 Share 方式，包括 flickr，但上手感觉不利索，不像名字取的那样 little。

我特别不喜欢它的截图方式，定位不如其他三个的十字交叉线来的方便：

不过，LittleSnapper 也有亮点：1) 组织管理功能比较强大，适合剪贴报爱好者；2）强大的网页截图功能，它自带 HTML 解析器，能定位到 Element，适合网页设计者。

系统自带

最后，不得不说，其实 Mac 系统自带的截图功能对付日常工作已经绰绰有余，截图质量更是没得说。再配上 Preview 做点简单的注释，80%的活都能应付。

VPN 就是翻墙的一种利器。但是要自己搭一个VPN实属不易，如果你用的是联通（原网通）的ADSL，可能更麻烦一点。

PPTP VPN 比较简单，没有特殊安全性需求的，推荐优先选择这种。搭建方法直接参照此文就行。一个 pptpd 就搞定了。注意别忘了打开 Masquerading/NAT。

我在浙江老家（电信 ADSL）的时候，就用以上配置轻松搞定了 PPTP VPN，终于可以在 iPhone 上玩 Tweetie 和 Facebook 了。

结果一回北京，PPTP VPN 马上不好使了：能够正常连接上，但是很快就会无法访问网络，并且 ping 报错 No buffer space available。

我不是网络专家，网络技术相当业余，无法确认是联通 ADSL 的问题，还是办理宽带时附赠的华为 EchoLife HG527-a 路由器的问题（有其他 ADSL 路由器的朋友可以帮忙试验一下），但总之是联通让我的 VPN 连不通了。

我本想用别的 PPTP VPN 试验一下，好确认不是我自己 VPN 的问题，但是一时间没找到可供试用的 VPN（有 PPTP VPN 的朋友可以帮忙试验一下）。于是，我又折腾了两天，搭了个 L2TP/IPsec VPN，终于又能逍遥游了。

搭建 L2TP/IPsec VPN 的方法请见此文。

可能遇到的问题和解决方法：

1. 连接不上，/var/log/auth.log 中有类似如下记录：

   Mar 10 11:01:36 hostname pluto[14061]: ERROR: asynchronous network error report on eth0 (sport=4500) for message to your.client.ip.address port 4500, complainant your.server,ip.address: No route to host [errno 113, origin ICMP type 3 code 1 (not authenticated)]

   在 ipsec.conf 中加上 leftnexthop=your.server.gateway.ip 应该可以解决。

2. 连接不上，/var/log/system 中有类似如下记录：

   Mar 11 14:44:20 hostname pppd[4407]: The remote system is required to authenticate itself
   Mar 11 14:44:20 hostname pppd[4407]: but I couldn't find any suitable secret (password) for it to use to do so.

   这是由于验证过程中未使用 l2tp-secrets 中的密码（至于为何如此我不懂，另请高人解释），而是使用 pptp（L2TP/IPsec 也是要走 pptp 的）的密码，所以需要在 /etc/ppp/chap-secrets 中设置密码（具体请见上面如何搭建 PPTP VPN）。

注：我不懂对对子，只是在乱吟。

Today is a big day in my life for two things.

First, my first iPhone app – Voodo – debuts on the App Store.

Second, my Wedding with J will take place tonight.

While we’ve received so many sincere blessings and gifts, I think it’s my responsibility to prepare the best gift for my bride, our wedding, and our future life. So I purposely scheduled the debut date of Voodo for today.

I am so excited that I can hardly wait for the moment to come.

婚礼上的魔术（Voodoo）

今天是个好日子、大日子。

我的第一个 iPhone app ─ Voodo ─ 正式登陆 App Store.

今晚是我和佳的婚礼。

我们收到了许多诚挚的祝福和礼物。但是，我觉得，我有责任和义务为我的新娘、我们的婚礼、以及我们未来的生活，精心准备一份最好的礼物。所以，我特意将 Voodo 的上架日期定为今天。

真是兴奋不已，迫不及待那一刻的到来。

1. query(uri, projection, selection = "column=" + value, selectionArgs = null, sortOrder)
2. query(uri, projection, selection = "column=?", selectionArgs = { value_as_string }, sortOrder)

Obviously, the first one is more straightforward and convenient. Then what’s good about the second one?

Let me try to sell the goodness of selectionArgs via a simple example.

Suppose you are querying contacts with phone number, say, “+8612345678901″. With the first style, you get the WHERE clause "number=+8612345678901" which is the result of string concatenation ‘"number=" + "+8612345678901"‘.

It is easy to see that phone numbers are not pure numbers, i.e., they are not numeric. For example, the number “(010) 87654321 ” and “010-87654321-001″, are valid phone numbers, but are neither valid integer nor real numbers ^(Of course, you don’t want to do the subtraction of the latter.)$. Thus, the the type of the number column (storage class in SQLite’s idiom) is TEXT.

From this nonnumeric phone number string raises a problem, a quite subtle one. With its dynamic type system、column affinity and type conversion, SQLite will try to convert “+8612345678901″ to a text string. But the express “+8612345678901″ is numeric originally, because it has no quote marks surrounding it, and numeric values are operated according numeric rules first. So it is first normalized to “8612345678901″, and then the normalized value is converted to a text string “‘8612345678901‘“.

So the query that is really fed into the SQLite engine is something like this:

But as a text string, ’8612345678901′ can not be matched with ‘+8612345678901′, and the query fails.

We were suffering this kind of adversity until selectionArgs came to save the day.

With the second style, Android SQL query builder will replace ?s in selection with the values from selectionArgs, in order that they appear in the selection. The values must be String and will be treated as text strings by SQLite, i.e., they must be converted to their String representation first if they are not String, and will be quoted automatically when replacing the ?s. So the query that is fed into the SQLite engine is something like this:

At this point, it doesn’t matter whether the underlying column type is really TEXT or not, because whatever the TEXT value is derived from, it can be correctly cast back to the original column type. The key point is that TEXT can be losslessly converted to any other types, but not necessarily vice versa as shown above.

In fact, we can stick to the first style by manually simulating the works done by Android SQL query builder this way:

But as you can see, it is such a tedious concatenation with just one query column, you don’t want to imagine the mess with more complex queries, do you?

Actually, I’m doomed to fail, because it is just Mission Impossible.

For the time being, a BroadcastReceiver for "android.intent.action.PHONE_STATE" is the only chance for application developers to generally probe for incoming calls. However, it comes too late.

Here is why.

com.android.internal.telephony.gsm.RIL.RILReceiver.run():                                               +---+ 
                                       android.net.LocalSocket.getInputStream() <-----------------------|   |
                                                                  /                                     |   |
                                                                 |                                      |   |
                                                                 v                                      | R |
  com.android.internal.telephony.gsm.RIL.readRilMessage(InputStream, byte[])                            | A |
  com.android.internal.telephony.gsm.RIL.processResponse(Parcel):                                       | D |
  Case 1: Unsolicited Commands - Incoming Call                                                          | I |
    com.android.internal.telephony.gsm.RIL.processUnsolicited(Parcel)                                   | O |
    com.android.internal.telephony.BaseCommands.mCallStateRegistrants.notifyRegistrants(AsyncResult)    |   |
    com.android.internal.telephony.gsm.CallTracker.sendMessage(Message)                                 |   |
                                                        |                                               |   |
                                                        |                                               | S |
                                                        v                                               | Y |
    com.android.internal.telephony.gsm.CallTracker.handleMessage(Message)                               | S |
    com.android.internal.telephony.gsm.CallTracker.pollCallsWhenSafe()                                  | T |
    com.android.internal.telephony.gsm.RIL.getCurrentCalls(Message)                                     | E |
    com.android.internal.telephony.gsm.RIL.send(RILRequest)                                             | M |
                                                     |                                                  |   |
                                                     |                                                  |   |
                                                     v                                                  |   |
    com.android.internal.telephony.gsm.RIL.RILSender.handleMessage(Message)                             |   |
                               android.net.LocalSocket.getOutputStream().write(byte[]) ---------------->|   |
                                                                                                        +---+    
  Case 2: Solicited Commands - Request Call Info
    com.android.internal.telephony.gsm.RIL.processSolicited(Parcel)
    com.android.internal.telephony.gsm.RIL.findAndRemoveRequestFromList(int)
    com.android.internal.telephony.gsm.RILRequest.mResult.sendToTarget()
                                                           |
                                                           |
                                                           v
    com.android.internal.telephony.gsm.CallTracker.handleMessage(Message)
    com.android.internal.telephony.gsm.CallTracker.handlePollCalls(AsyncResult)
    com.android.internal.telephony.gsm.GSMPhone.notifyNewRingingConnection(Connection)
    com.android.internal.telephony.PhoneBase.notifyNewRingingConnectionP(Connection):
      com.android.phone.CallNotifier.sendMessage(Message)
                                           |
                                           |
                                           v
      com.android.phone.CallNotifier.handleMessage(Message)
      com.android.phone.CallNotifier.onNewRingingConnection(AsyncResult)
      com.android.phone.PhoneUtils.showIncomingCallUi() <---------------- Users see incoming call
 
    com.android.internal.telephony.gsm.CallTracker.updatePhoneState()
    com.android.internal.telephony.gsm.GSMPhone.notifyPhoneStateChanged()
    com.android.internal.telephony.DefaultPhoneNotifier.notifyPhoneState(Phone)
    com.android.server.TelephonyRegistry.notifyCallState(int, String)
    com.android.server.TelephonyRegistry.broadcastCallStateChanged(int, String) <--- Too late to interfere

Today, I stumbled upon SugarSync which seems very promising. The most outstanding advantage of SugarSync over DropBox is its flexibility to backup/sync any folders. You can see the detailed comparison between SugarSync and other prominent competitors here.

However, just before I set out to download SugarSync Manager 1.6.2 for Mac (Beta), I glimpsed the Known Issues ^(The more software you use, especially the more software you develop, the more wary of software you are.)$, and one of them scared the pants off me. It said:

If you are using a mac that has been formatted with a case-sensitive filesystem instead of the default case-insensitive filesystem, SugarSync may not function properly due to incorrect case of paths.

I am definitely one of those implied idiots that formatted their effeminate Macs with Case-Sensitive filesystems just to show more masculine. Fine, in fact, I am a 6-year-old Linux user. Whatsoever, what on earth makes you developers resist case-sensitivity so much that you prefer to turn down your peer Unix developers ^(I don’t think Windows users care about case-sensitivity because they never have one, and aren’t all Unix (before Mac OS X) users developers?)$? Are you as arrogant as Adobe?

I am also a coward who dare not to take a risk. What do you mean by “may not function properly“? ^(Maybe, by “may not” instead of “will not”, they mean it works well even on case-sensitive filesystems only if there are not any files or directories distinguishable only by case?)$ Will it damage my original data, or just refuse to backup them? And why don’t you just say “SugarSync does not support case-sensitive filesystems (right now), so do not use SugarSync on them.”?

What if I took the risk and lost my data? So then you can disclaim “We have warned you that it may not function properly. You made the decision. You take the responsibility.”?

I think there are some basic moral code that a properly functioning vendor should follow:

• For cases where your product function perfectly, proudly announce them and dutifully guarantee them.
• For cases where your product does not function perfectly, describe the deficiencies clearly.
• For cases you are not sure, confess candidly that even you are not sure and advise users against using it in those cases.
• Never make any cunning disclaimers, because, you see, weasel words “may not function properly“, or even hurt your prospects.