纯真IP数据库格式详解

摘要
网络上的IP数据库以纯真版的最为流行，LumaQQ也采用了纯真版IP数据库做为IP查询功能的 基础。不过关于其格式的文档却非常之少，后来终于在网上找到了一份文档，得以了解其内幕，不过那份文档寥寥数语，也是颇为耐心才读明白。在这里我重写一 份，以此做为LumaQQ开发者文档的一部分，我想还是必要的。本文详细介绍了纯真IP数据库的格式，并且给出了一些Demo以供参考。

Luma, 清华大学
修改日期： 2005/01/14

Note: 在此感谢纯真IP数据库作者金狐和那唯一一份文档的作者。

修改历史:
2005-01-14 修改了原来一些表达不清和错误的地方

自从有了IP数据库这种东西，QQ外挂的显示IP功能也随之而生，本人见识颇窄，是否还有其他应用不得而知，不过，IP数据库确实是个不错的东西。 如今网络上最流行的IP数据库我想应该是纯真版的（说错了也不要扁我），迄今为止其IP记录条数已经接近30000，对于有些IP甚至能精确到楼层，不亦 快哉。2004年4、5月间，正逢LumaQQ破土动工，为了加上这个人人都喜欢，但是好像人人都不知道为什么喜欢的显IP功能，我也采用了纯真版IP数 据库，它的优点是记录多，查询速度快，它只用一个文件QQWry.dat就包含了所有记录，方便嵌入到其他程序中，也方便升级。

基本结构

QQWry.dat文件在结构上分为3块：文件头，记录区，索引区。一般我们要查找IP时，先在索引区查找记录偏移，然后再到记录区读出信息。由于 记录区的记录是不定长的，所以直接在记录区中搜索是不可能的。由于记录数比较多，如果我们遍历索引区也会是有点慢的，一般来说，我们可以用二分查找法搜索 索引区，其速度比遍历索引区快若干数量级。图1是QQWry.dat的文件结构图。

图1. QQWry.dat文件结构

要注意的是，QQWry.dat里面全部采用了little-endian字节序

一. 了解文件头

QQWry.dat的文件头只有8个字节，其结构非常简单，首四个字节是第一条索引的绝对偏移，后四个字节是最后一条索引的绝对偏移。

二. 了解记录区

每条IP记录都由国家和地区名组成，国家地区在这里并不是太确切，因为可能会查出来“清华大学计算机系”之类的，这里清华大学就成了国家名了，所以 这个国家地区名和IP数据库制作的时候有关系。所以记录的格式有点像QName，有一个全局部分和局部部分组成，我们这里还是沿用国家名和地区名的说法。

于是我们想象着一条记录的格式应该是: [IP地址][国家名][地区名]，当然，这个没有什么问题，但是这只是最简单的情况。很显然，国家名和地区名可能会有很多的重复，如果每条记录都保存一 个完整的名称拷贝是非常不理想的，所以我们就需要重定向以节省空间。所以为了得到一个国家名或者地区名，我们就有了两个可能：第一就是直接的字符串表示的 国家名，第二就是一个4字节的结构，第一个字节表明了重定向的模式，后面3个字节是国家名或者地区名的实际偏移位置。对于国家名来说，情况还可能更复杂 些，因为这样的重定向最多可能有两次。

那么什么是重定向模式？根据上面所说，一条记录的格式是[IP地址][国家记录][地区记录]，如果国家记录是重定向的话，那么地区记录是有可能没有的，于是就有了两种情况，我管他叫做模式1和模式2。我们对这些格式的情况举图说明：

图2. IP记录的最简单形式

图2表示了最简单的IP记录格式，我想没有什么可以解释的

图3. 重定向模式1

图3演示了重定向模式1的情况。我们看到在模式1的情况下，地区记录也跟着国家记录走了，在IP地址之后只剩下了国家记录的4字节，后面3个字节构成了一个指针，指向了实际的国家名，然后又跟着地址名。模式1的标识字节是0x01。

图4. 重定向模式2

图4演示了重定向模式2的情况。我们看到了在模式2的情况下（其标识字节是0x02），地区记录没有跟着国家记录走，因此在国家记录之后4个字节之 后还是有地区记录。我想你已经明白了模式1和模式2的区别，即：模式1的国家记录后面不会再有地区记录，模式2的国家记录后会有地区记录。下面我们来看一 下更复杂的情况。

图5. 混和情况1

图5演示了当国家记录为模式1的时候可能出现的更复杂情况，在这种情况下，重定向指向的位置仍然是个重定向，不过第二次重定向为模式2。大家不用担 心，没有模式3了，这个重定向也最多只有两次，并且如果发生了第二次重定向，则其一定为模式2，而且这种情况只会发生在国家记录上，对于地区记录，模式1 和模式2是一样的，地区记录也不会发生2次重定向。不过，这个图还可以更复杂，如图7：

图6. 混和情况2

图6是模式1下最复杂的混和情况，不过我想应该也很好理解，只不过地区记录也来重定向而已，有一点我要提醒你，如果重定向的地址是0，则表示未知的地区名。

所以我们总结如下：一条IP记录由[IP地址][国家记录][地区记录]组成，对于国家记录，可以有三种表示方式：字符串形式，重定向模式1和重定 向模式2。对于地区记录，可以有两种表示方式：字符串形式和重定向，另外有一条规则：重定向模式1的国家记录后不能跟地区记录。按照这个总结，在这些方式 中合理组合，就构成了IP记录的所有可能情况。

设计的理由

在我们继续去了解索引区的结构之前，我们先来了解一下为何记录区的结构要如此设计。我想你可能想到了答案：字符串重用。没错，在这种结构下，对于一 个国家名和地区名，我只需要保存其一次就可以了。我们举例说明，为了表示方便，我们用小写字母代表IP记录，C表示国家名，A表示地区名：

1. 有两条记录a(C1, A1), b(C2, A2)，如果C1 = C2, A1 = A2，那么我们就可以使用图3显示的结构来实现重用
2. 有三条记录a(C1, A1), b(C2, A2), c(C3, A3)，如果C1 = C2, A2 = A3，现在我们想存储记录b，那么我们可以用图6的结构来实现重用
3. 有两条记录a(C1, A1), b(C2, A2)，如果C1 = C2，现在我们想存储记录b，那么我们可以采用模式2表示C2，用字符串表示A2

你可以举出更多的情况，你也会发现在这种结构下，不同的字符串只需要存储一次。

了解索引区

在"了解文件头"部分，我们说明了文件头实际上是两个指针，分别指向了第一条索引和最后一条索引的绝对偏移。如图8所示：

图8. 文件头指向索引区图示

实在是很简单，不是吗？从文件头你就可以定位到索引区，然后你就可以开始搜索IP了！每条索引长度为7个字节，前4个字节是起始IP地址，后三个字 节就指向了IP记录。这里有些概念需要说明一下，什么是起始IP，那么有没有结束IP？ 假设有这么一条记录：166.111.0.0 - 166.111.255.255，那么166.111.0.0就是起始IP，166.111.255.255就是结束IP，结束IP就是IP记录中的那头 4个字节，这下你应该就清楚了吧。于是乎，每条索引配合一条记录，构成了一个IP范围，如果你要查找166.111.138.138所在的位置，你就会发 现166.111.138.138落在了166.111.0.0 - 166.111.255.255 这个范围内，那么你就可以顺着这条索引去读取国家和地区名了。那么我们给出一个最详细的图解吧：

图9. 文件详细结构

现在一切都清楚了是不是？也许还有一点你不清楚，QQWry.dat的版本信息存在哪里呢？ 答案是：最后一条IP记录实际上就是版本信息，最后一条记录显示出来就是这样：255.255.255.0 255.255.255.255 纯真网络 2004年6月25日IP数据。OK，到现在你应该全部清楚了。

Demo

下一步：我给出一个读取IP记录的程序片断，此片断摘录自LumaQQ源文件edu.tsinghua.lumaqq.IPSeeker.java，如果你有兴趣，可以下载源代码详细看看。

 /**
  * 给定一个ip国家地区记录的偏移，返回一个IPLocation结构
  * @param offset 国家记录的起始偏移
  * @return IPLocation对象
  */
 private IPLocation getIPLocation(long offset) {
  try {
   // 跳过4字节ip
   ipFile.seek(offset + 4);
   // 读取第一个字节判断是否标志字节
   byte b = ipFile.readByte();
   if(b == REDIRECT_MODE_1) {
    // 读取国家偏移
    long countryOffset = readLong3();
    // 跳转至偏移处
    ipFile.seek(countryOffset);
    // 再检查一次标志字节，因为这个时候这个地方仍然可能是个重定向
    b = ipFile.readByte();
    if(b == REDIRECT_MODE_2) {
     loc.country = readString(readLong3());
     ipFile.seek(countryOffset + 4);
    } else
     loc.country = readString(countryOffset);
    // 读取地区标志
    loc.area = readArea(ipFile.getFilePointer());
   } else if(b == REDIRECT_MODE_2) {
    loc.country = readString(readLong3());
    loc.area = readArea(offset + 8);
   } else {
    loc.country = readString(ipFile.getFilePointer() - 1);
    loc.area = readArea(ipFile.getFilePointer());
   }
   return loc;
  } catch (IOException e) {
   return null;
  }
 } 

 /**
  * 从offset偏移开始解析后面的字节，读出一个地区名
  * @param offset 地区记录的起始偏移
  * @return 地区名字符串
  * @throws IOException 地区名字符串
  */
 private String readArea(long offset) throws IOException {
  ipFile.seek(offset);
  byte b = ipFile.readByte();
  if(b == REDIRECT_MODE_1 || b == REDIRECT_MODE_2) {
   long areaOffset = readLong3(offset + 1);
   if(areaOffset == 0)
    return LumaQQ.getString("unknown.area");
   else
    return readString(areaOffset);
  } else
   return readString(offset);
 }

 /**
  * 从offset位置读取3个字节为一个long，因为java为big-endian格式，所以没办法
  * 用了这么一个函数来做转换
  * @param offset 整数的起始偏移
  * @return 读取的long值，返回-1表示读取文件失败
  */
 private long readLong3(long offset) {
  long ret = 0;
  try {
   ipFile.seek(offset);
   ipFile.readFully(b3);
   ret |= (b3[0] & 0xFF);
   ret |= ((b3[1] << 8) & 0xFF00);
   ret |= ((b3[2] << 16) & 0xFF0000);
   return ret;
  } catch (IOException e) {
   return -1;
  }
 } 
 
 /**
  * 从当前位置读取3个字节转换成long
  * @return 读取的long值，返回-1表示读取文件失败
  */
 private long readLong3() {
  long ret = 0;
  try {
   ipFile.readFully(b3);
   ret |= (b3[0] & 0xFF);
   ret |= ((b3[1] << 8) & 0xFF00);
   ret |= ((b3[2] << 16) & 0xFF0000);
   return ret;
  } catch (IOException e) {
   return -1;
  }
 }

 /**
  * 从offset偏移处读取一个以0结束的字符串
  * @param offset 字符串起始偏移
  * @return 读取的字符串，出错返回空字符串
  */
 private String readString(long offset) {
  try {
   ipFile.seek(offset);
   int i;
   for(i = 0, buf[i] = ipFile.readByte(); buf[i] != 0; buf[++i] = ipFile.readByte());
   if(i != 0) 
       return Utils.getString(buf, 0, i, "GBK");
  } catch (IOException e) {   
      log.error(e.getMessage());
  }
  return "";
 }

代码并不复杂，getIPLocation是主要方法，它检查国家记录格式，并针对字符串形式，模式1，模式2采用不同的代码，readArea则相对简单，因为只有字符串和重定向两种情况需要处理。

总结

纯真IP数据库的结构使得查找IP简单迅速，不过你想要编辑它却是比较麻烦的，我想应该需要专门的工具来生成QQWry.dat文件，由于其文件格式的限制，你要直接添加IP记录就不容易了。不过，能查到IP已经很开心了，希望纯真记录越来越多～。

在奇趣（Trolltech），为了改进Qt的开发体验，我们做了大量的研究。这篇文章里，我打算分享一些我们的发现，以及一些我们在设计Qt4时用到的原则，并且展示如何把这些原则应用到你的代码里。

• 好的API的六个特性
• 便利陷阱
• 布尔参数陷阱
• 静态多态
• 命名的艺术
• 指针还是引用？
• 例子：QProgressBar
• 如何把API设计好

设计应用程序接口，API，是很难的。这是一门和设计语言同样难的艺术。这里可以选择太多的原则，甚至有很多原则和其他原则有矛盾。

现在，计算机科学教育把很大的力气放在算法和数据结构上，而很少关注设计语言和框架背后的原则。这让应用程序员完全没有准备去面对越来越重要的任务：创造可重用的组件。

在面向对象语言普及之前，可重用的通用代码大部分是由库提供者写的，而不是应用程序员。在Qt的世界里，这种状况有了明显的改善。在任何时候，用Qt编程就是写新的组件。一个典型的Qt应用程序至少都会有几个在程序中反复使用的自定义组件。一般来说，同样的组件会成为其他应用程序的一部分。KDE，K桌面环境，走得更远，用许多追加的库来扩展Qt，实现了数百个附加类。（一般来说，一个类就是一个可重用组件，原文这里没有写清楚。）

但是，一个好的，高效的C++ API是由什么组成的呢？是好还是坏，取决于很多因素——比如，手头的工作和特定的目标群体。好的API有很多特性，一些特性是大家都想要的，而另一些则是针对特定问题域的。

API是面向程序员的，用来描述提供给最终用户的GUI是什么样子。API中的P带表程序员（Programmer），而不是程序（Program），用来强调API是给程序员用的，给人类的程序员用的。

我们坚信API应该是最小化且完整的，拥有清晰且简单的语义，直觉化，容易记忆，并且引导人写出易读的代码。

• 最小化：最小化的API是指一个类尽可能只拥有最少的公开成员且尽可能只拥有最少的类。这个原则可以让API更简单易懂，更好记，更容易除错，且更容易改变。
• 完整的：完整的API是指要提供所有期望的功能。这个可能与最小化原则相冲突。另外，如果一个成员函数属于一个不应该属于的类，很多潜在的使用者都会找不到这个函数。
• 拥有清晰且简单的语义：就像其他设计工作一样，你必须遵守最小惊奇原则（the principle of least surprise）。让常见的任务简单易行。不常见的工作可行，但不会让用户过分关注。解决特殊问题时，不要让解决方案没有必要的过度通用。（比如，Qt3中的QMimeSourceFactory可以通过调用QImageLoader来实现不同的API。）
• 直觉化：就像电脑上的其他东西一样，API必须是直觉化的。不同的经验和背景会导致在判断什么是直觉而什么不是时不同的感觉。如果一个中级用户不读文档就可以使用（a semi-experienced user gets away without reading the documentation，没懂这里的get away该怎么翻译），并且一个程序员不懂API就可以理解缩写的代码，这种API就是直觉化的。
• 易于记忆：让API易于记忆，使用统一且精确的命名方法。使用可识别的模式和概念，并且避免缩写。
• 引导易读的代码（Lead to readable code）：代码一经写就，会读（并且除错和修改）多次。易读的代码可能会花点时间来写，但是可以节省产品周期中的其他时间。

最后，记住，不同类型的用户会用到API的不同部分。虽然简单的实例化一个Qt类是非常直觉化的，让资深专家在试图子类化之前读一遍文档，是很合理的。

这是个常见的误解：更好的API，用更少的代码完成一件事。永远记住代码一次写就，之后需要不断的阅读并理解。比如：

    QSlider *slider = new QSlider(12, 18, 3, 13, Qt::Vertical,
0, "volume");

远比下面那样难读（甚至难写）：

    QSlider *slider = new QSlider(Qt::Vertical);
slider->setRange(12, 18);
slider->setPageStep(3);
slider->setValue(13);
slider->setObjectName("volume");

布尔参数通常会导致不易读的代码。更进一步，给一个已经存在的函数加入一个布尔参数，这常常是个错误。在Qt里，一个传统的例子是repaint()，这个函数带有一个布尔参数，来标识是否擦除背景（默认擦除）。这让代码通常写成：

    widget->repaint(false);

初学者很容易把这句话理解成“别重画”！

这样做是考虑到布尔参数可以减少一个函数，避免代码膨胀。事实上，这反而增加了代码量。有多少Qt用户真的记住了下面三行程序都是做什么的？

    widget->repaint();
widget->repaint(true);
widget->repaint(false);

一个好一些的API可能看起来是这样：

    widget->repaint();
widget->repaintWithoutErasing();

在Qt4里，我们重新设计了widget，使得用户不再需要不重画背景的重画widget，来解决这个问题。Qt4原生支持双缓存，废掉了这个特性。

这里还有一些例子：

    widget->setSizePolicy(QSizePolicy::Fixed,
QSizePolicy::Expanding, true);
textEdit->insert("Where's Waldo?", true, true, false);
QRegExp rx("moc_*.c??", false, true);

一个显而易见的解决方法是，使用枚举类型代替布尔参数。这正是我们在Qt4中QString大小写敏感时的处理方法。比较：

    str.replace("%USER%", user, false);               // Qt 3
str.replace("%USER%", user, Qt::CaseInsensitive); // Qt 4

相似的类应该含有相似的API。在必要的时候——就是说，需要使用运行时多态的时候——这可以通过继承实现。但是多态依旧会发生在设计时期。比如，如果你用QListBox代替QComboBox，或者用QSlider代替QSpinBox，你会发现相似的API使这种替换非常容易。这就是我们所说的“静态多态”。

静态多态也使API和程序模式更容易记忆。作为结论，一组相关类使用相似的API，有时要比给每个类提供完美的单独API，要好。

（译注：C++ 0x将要引入的concept，就是静态多态的语法层实现。这个要比单独的函数名相似更强大且易用。）

命名，大概是设计API时唯一最重要的问题了。该怎么称呼这个类？成员函数该叫什么？

通用的命名规则

一些规则通常对所有名字都是有用的。首先，就像我之前提到的，别用缩写。甚至很明显的缩写，比如“prev”表示“previous”从长远看也是不划算的，因为用户必须记住哪些词是缩写。

如果API本身不一致，事情自然会变得很糟糕，比如， Qt3有activatePreviousWindow()和fetchPrev()。坚持“没有缩写”的规则更容易创建一致的API。

另一个重要但更加微妙的规则是，在设计类的时候，必须尽力保证子类命名空间的干净。在Qt3里，没有很好的遵守这个规则。比如，拿QToolButton来举例。如果你在Qt3里，对一个QToolButton调用name()、caption()、text()或者textLabel()，你希望做什么呢？你可以在Qt Designer里拿QToolButton试试：

• name属性继承自QObject，表示一个对象用于除错和测试的内部名字。
• caption属性继承自QWidget，表示窗口的标题，这个标题在视觉上对QToolButton没有任何意义，因为他们总是跟随父窗口而创建。
• text属性继承自QButton，一般情况下是按钮上现实的文字，除非useTextLabel为真。
• textLabel在QToolButton里声明，并且在useTextLabel为真时显示在按钮上。

由于对可读性的关注，name在Qt4里被称作objectName，caption变成了windowsTitle，而在QToolButton里不再有单独的textLabel属性。

给类命名

标识一组类而不是单独给每个类找个恰当的名字。比如，Qt4里所有模式感知项目的视图类（model-aware item view classes）都拥有-View的后缀（QListView、QTableView和QTreeView），并且对应基于项目的类都用后缀-Widget代替（QListWidget、QTableWidget和QTreeWidget）。

给枚举类型及其值命名

当声明枚举时，时刻记住，在C++（不像Java和C#）中，使用枚举值不需要类型信息。下面的例子演示了给枚举值起个太过常用的名字所引起的危害：

    namespace Qt
{
enum Corner { TopLeft, BottomRight, ... };
enum CaseSensitivity { Insensitive, Sensitive };
...
};
tabWidget->setCornerWidget(widget, Qt::TopLeft);
str.indexOf("$(QTDIR)", Qt::Insensitive);

在最后一行，Insensitive是什么意思？一个用于命名枚举值的指导思想是，在每个枚举值里，至少重复一个枚举类型名中的元素：

    namespace Qt
{
enum Corner { TopLeftCorner, BottomRightCorner, ... };
enum CaseSensitivity { CaseInsensitive,
CaseSensitive };
...
};
tabWidget->setCornerWidget(widget, Qt::TopLeftCorner);
str.indexOf("$(QTDIR)", Qt::CaseInsensitive);

当枚举值可以用“或”连接起来当作一个标志时，传统的做法是将“或”的结果作为一个int保存，这不是类型安全的。Qt4提供了一个模板类 QFlags<T>来实现类型安全，其中T是个枚举类型。为了方便使用，Qt为很多标志类名提供了typedef，所以你可以使用类型 Qt::Alignment代替QFlags<Qt::AlignmentFlag>。

为了方便，我们给枚举类型单数的名字（这样表示枚举值一次只能有一个标志），而“标志”则使用复数名字。比如：

    enum RectangleEdge { LeftEdge, RightEdge, ... };
typedef QFlags<RectangleEdge> RectangleEdges;

有些情况下，“标志“类使用了单数的名字。这时，枚举类使用-Flag做后缀：

    enum AlignmentFlag { AlignLeft, AlignTop, ... };
typedef QFlags<AlignmentFlag> Alignment;

（这里为啥不是把”标志“类用-Flag做后缀，而是把枚举值做后缀呢？感觉有点混淆……）

给函数和参数命名

给函数命名的一个规则是，名字要明确体现出这个函数是否有副作用。在Qt3，常数函数QString::simplifyWhiteSpace()违反了这个原则，因为它返回类一个QString实例，而不是像名字所提示的那样，更改了调用这个函数的实例本身。在Qt4，这个函数被重命名为QString::simplified()。

参数名是程序员的重要信息来源，虽然在使用API时，并不直接展示在代码里。由于现代IDE在程序员写代码时可以自动显示参数名（就是自动感知或者自动补全之类的功能），值得花时间给头文件里声明的参数一个合适的名字，并且在文档中也使用相同的名字。

给布尔值设置函数（Setter）、提取函数（Getter）和属性命名

给布尔属性的设置函数和提取函数一个合适的名字，总是非常痛苦的。提取函数应该叫做checked()还是isChecked()？scrollBarsEnabled()还是areScrollBarEnabled()?

在Qt4里，我们使用下列规则命名提取函数：

• 形容类的属性使用is-前缀。比如：
  • isChecked()
  • isDown()
  • isEmpty()
  • isMovingEnable()
  另外，应用到复数名词的形容类属性没有前缀：
  • scrollBarsEnabled()，而不是areScrollBarsEnabled()
• 动词类的属性不使用前缀，且不使用第三人称（-s）：
  • acceptDrops()，而不是acceptsDrops()
  • allColumnsShowFocus()
• 名词类的属性，通常没有前缀：
  • autoCompletion()，而不是isAutoCompletion()
  • boundaryChecking()
  有时，没有前缀就会引起误解，这种情况使用前缀is-：
  • isOpenGLAvailable()，而不是openGL()
  • isDialog()，而不是dialog()
  （通过调用dialogue()方法，正常情况下会期望返回一个QDialog*的实例。）

设置函数名字继承自提取函数名，只是移掉了所有前缀，并使用set-做前缀，比如：setDown()还有setScrollBarsEnabled()。属性的名字与提取函数相同，只是去掉了前缀。

传出参数的最佳选择是什么，指针还是引用？

    void getHsv(int *h, int *s, int *v) const
void getHsv(int &h, int &s, int &v) const

大部分C++书推荐在能用引用的地方就用引用，这是因为一般认为引用比指针更“安全且好用”。然而，在奇趣（Trolltech），我们倾向使用指针，因为这让代码更易读。比较：

    color.getHsv(&h, &s, &v);
color.getHsv(h, s, v);

只有第一行能清楚的说明，在函数调用后，h、s和v将有很大几率被改动。

为了展示如何实际应用这些概念，我们将学习Qt3中的API QProgressBar并和Qt4里相通的API做比较。在Qt3里：

    class QProgressBar : public QWidget
{
...
public:
int totalSteps() const;
int progress() const;
const QString &progressString() const;
bool percentageVisible() const;
void setPercentageVisible(bool);
void setCenterIndicator(bool on);
bool centerIndicator() const;
void setIndicatorFollowsStyle(bool);
bool indicatorFollowsStyle() const;
public slots:
void reset();
virtual void setTotalSteps(int totalSteps);
virtual void setProgress(int progress);
void setProgress(int progress, int totalSteps);
protected:
virtual bool setIndicator(QString &progressStr,
int progress,
int totalSteps);
...
};

API相当复杂，且不统一。比如，仅从名字reset()并不能理解其作用，setTotalSteps()和setProgress()是紧耦合的。

改进API的关键，是注意到QProgressBar和Qt4的QAbstractSpinBox类及其子类QSpinBox，QSlider和QDial很相似。解决方法？用minimum、maximum和value代替progress和totalSteps。加入alueChanged()信号。加入setRange()函数。

之后观察progressString、percentage和indicator实际都指一个东西：在进度条上显示的文字。一般来说文字是百分比信息，但是也可以使用setIndicator()设为任意字符。下面是新的API：

    virtual QString text() const;
void setTextVisible(bool visible);
bool isTextVisible() const;

默认的文字信息是百分比信息。文字信息可以藉由重新实现text()而改变。

在Qt3 API中，setCenterIndicator()和setIndicatorFollowStyle()是两个影响对齐的函数。他们可以方便的由一个函数实现，setAlignment()：

    void setAlignment(Qt::Alignment alignment);

如果程序员不调用setAlignment()，对齐方式基于当前的风格。对于基于Motif的风格，文字将居中显示；对其他风格，文字将靠在右边。

这是改进后的QProgressBar API：

    class QProgressBar : public QWidget
{
...
public:
void setMinimum(int minimum);
int minimum() const;
void setMaximum(int maximum);
int maximum() const;
void setRange(int minimum, int maximum);
int value() const;
virtual QString text() const;
void setTextVisible(bool visible);
bool isTextVisible() const;
Qt::Alignment alignment() const;
void setAlignment(Qt::Alignment alignment);
public slots:
void reset();
void setValue(int value);
signals:
void valueChanged(int value);
...
};

API需要质量保证。第一个修订版不可能是正确的；你必须做测试。写些用例：看看那些使用了这些API的代码，并验证代码是否易读。

其他的技巧包括让别的人分别在有文档和没有文档的情况下，使用这些API；或者为API类写文档（包括类的概述和独立的函数）。

当你卡住时，写文档也是一种获得好名字的方法：仅仅是尝试把条目（类，函数，枚举值，等等呢个）写下来并且使用你写的第一句话作为灵感。如果你不能找到一个精确的名字，这常常说明这个条目不应该存在。如果所有前面的事情都失败了并且你确认这个概念的存在，发明一个新名字。毕竟，“widget”、 “event”、“focus”和“buddy”这些名字就是这么来的。