BeInternetCentral

version 0.5 - DRAFT

written by Hubert Figuière <hfiguiere@teaser.fr>
July 13th 1997

If you have any trouble using this software, feel free to contact me at: <hfiguiere@teaser.fr>. I'll accept comments, ideas, flames, bugs, etc.

Content

What is it ?
How do I use it ?
API Reference
1. Global Functions
2. The BICRegistry
  1. Introduction
  2. Registry storage
  3. Personality
  4. Key access
  5. Thread safeness
Music

What is it ?

BeInternetCentral (aka BIC) is a global internet configuration utility for BeOS. It's goal is to provide a standard way to configure internet settings under BeOS, for use by any application. It also provide URL parsing and opening features.

It's main inspiration stream is from InternetConfig for MacOS. InternetConfig was designed and written by Peter Lewis and Quinn "the Eskimo". See http://www.quinn.echidna.id.au/Quinn/Config/ for more informations.

BIC is free and provided with full source. It is public domain. Anybody is encouraged to make use of it.

Currently BIC is in the prerelease state for evaluation, comment and review purpose. It is NOT feature complete.

How do I use it ?

There are two uses. As a user and as a programer.

As a user

As user it means to configure you whole system for the Internet. Note that when multi-user will come, it will support it.

The BeInternetCentral application will allow you to set up everything. Then, any other software that make use of it will be ready as soon as you install it.

This may sound similar the the E-mail preferences panel that comes with BeOS. In fact it is more advanced and more extensible. Later version will fully integrate this BeOS feature...

As a programmer

As a programmer it means that you will use BIC functions for your own program. If you want to allow the use to specify hios e-mail address, you don't need to write a GUI for this. Uses BeInternetCentral. You don't need to specifically write Internet apps to need BIC. A text editor can be in need of BIC just to open URLs.

To use BIC in your programs, you need to include the libbic.a librarie into you project and #include the file libbic.h in the needed source files. Later version will be a shared library with a small glue lib for weak linking.

The first step is to create a registry using create_bic_registry(). Then after that, you'll only need to call the registry methods...

Have a look at the BICApplication.cpp file in the app directory of the BIC distribution to learn how to use this.

The API Reference section will tell describe the programmatic interface for BIC.

API reference

Here is a description of the BeInternetCentral API. Everything it in the libbic.h. Don't forget to include libbic.a in you project.

What is missing

Currently, the following feature are either not documented, not implemented or not working correctly:

Changing storage path.
Changes notification
Personality management (BeInternetCentral application)
Helpers for URLs
URL parsing and opening
Integration with BeOS' E-mail preferences

These functionalities will be implemented later.

Global functions

This two functions are the only function you really link against. Everything else will be determined by vtable from the BICRegistry object instantied. They are the only way you can instantiate a BICRegistry.



status_t create_bic_registry(BICRegistry * & registry, const bic_version & vers)

Instantiate the registry using a particular version of the API. You should use BIC_CURRENT_VERSION as defined in the BIC header libbic.h.

It is up to the application to manage the versions of BIC that are installed...

registry [o] : the registry that will be instantiated. In case of failure, it will be set to NULL.
vers [i/o] : the needed version... Should be most of the time BIC_CURRENT_VERSION. Returned here is the version supported/used.
The function returns BIC_VERSION_NOT_AVAILABLE if the versions is incorrect. If created, it returns the BICRegistry::InitCheck() value. Future version might theorically support earlier versions. This is to be determined.



status_t dispose_bic_registry(BICRegistry * & registry)

Dispose the registry... Return B_BAD_VALUE if pointer is NOT a registry or not valid. Otherwise returns B_NO_ERROR.

The BICRegistry

Introduction

The BICRegistry is the main part of BIC. It contains key a way to acces to those keys. It is instantiated by the create_bic_registry() and dispose_bic_registry(). This class is "hidden" from the linkage to the client application, but it is used as an interface to the BIC system through virtual functions.

BIC makes use of keys. Keys are storage units stored into a registry. There is one registry per user (in $HOME/config, currently /boot/home/config in BeOS PR). You may need to use a different registry, but I don't recommend this since it may confuse the user.

The registry is stored in a file (see Registry Storage later). You may specify a different storage path and/or filename for custom storage purpose. This is currently not supported, the default storage may be enough in the first time.

Each key is specified by a key id which is basically a base name, all along with an attribute. The attribute is optionnal. The combination of both makes a unique name. Each key contains a value which is a string containing formatted datas. Most of the time a string is enough. It you need to store a numeric, it is up to you to provide the encoding... <In the future, BIC might provide such services>
Key names and attribute names must only use [A-Z,a-z] caracters. Any other caracter is currently reserved for future use (version 1.0 will clarify this point). Names are case sensitive.

Here is the list of the predefined keys constants (a * indicates that the key use the personality attribute):

KEY_REAL_NAME* : the real name
KEY_EMAIL_ADRESS* : the email address
KEY_ORGANIZATION* :
KEY_POP_USERNAME* : the POP user name
KEY_POP_PASSWORD* : the POP password
KEY_POP_HOST* : the POP server host name
KEY_SMTP_HOST* : the SMTP host name
KEY_POP_AUTHENTIFICATION* : the authentification method for POP (Password or APOP)
KEY_NNTP_SERVER : the News server name
KEY_NNTP_LOGIN : the News server login (if needed)
KEY_NNTP_PASSWORD : the News server password (if needed)

You should use those constants (integrated into the libbic.a) to retrieve those key values.

NOTE: This system may duplicate the default e-mail settings of BeOS, but in fact it will extends it.

Registry Storage

The Registry is stored in a file. It is a flattened BMessage, but currently you don't need to know that... Everything is abstracted. <Those functions are not really supported yet.>



status_t BICRegistry::SetRegPath(const char * dir, const char * name)

This method set the registry path to the path given...

dir [i] : path to the directory
name [i] : name of the registry file. If "" or NULL, then the default name is used instead. This allow lookin for a registry file in another directory.



status_t BICRegistry::ResetRegPath(void)

Reset the registry file path to the default path which is $HOME/config

Personality

Personality represent different identity that someone may use. This is for example used if you have several e-mails, etc. Personality is the attribute that must be used with attributed keys.
There is at least one personality, and one of them is always the default personality. <Currently, you can't add personalities. This will be made a little bit later.>



status_t BICRegistry::GetPersonality(const int32 index, key_attribute_id personality, ssize_t & size) const

Retrieves an indexed personality attribute.

index [i] : index of the attribute. Use BICRegistry::CountPersonality() to retrieves the number available.
personality [i/o] : string buffer where to store the attribute. Should be enough large to contains BIC_ATTRIBUTE_LENGTH chars. (one more byte is required for the terminating NULL char). If provided buffer is to small, "" is returned and size contains the required size.
size [i/o] : the size in bytes of the ID... returns the real size. If provided buffer is to small, contains the needed size.
If it return BIC_ATTRIBUTE_NOT_FOUND, this means that the attribute as NOT been found... If it returns BIC_BUFFER_TO_SMALL, this means that the buffer is not large enough. It should be at least BIC_ATTRIBUTE_LENGTH + 1 large...



status_t BICRegistry::CountPersonality(int32 & count) const

Retrieves the number of available personalities.

count [o] : the number of available personality IDs.
return B_NO_ERROR or B_ATTRIBUTE_NOT_FOUND if there is an error retrieving attributes. BIC_NO_INIT means that BICRegistry has not been initialized properly.


char * BICRegistry::GetDefaultPersonality() const
status_t BICRegistry::SetDefaultPersonality(const key_attribute_id personality);

GetDefaultPersonality() retrieves the default personality. It can be directly used to acces to an attributed key when you don't just want to acces the default one. It return a pointer to the string that you have to copy.

The pointer will remain always valid unless you dispose de BICRegistry object (even if its content may change).

SetDefaultPersonality() sets personality as the default personality. It return B_NO_ERROR if everything is OK. It create this personality if it does not exists yet.

Key Access

Keys are accessed usinbg their name and their attribute. If it has no attribute, the "" string should be passed.
If you do want to use the default personality attribute, pass BICRegistry::GetDefaultPersonality().

It is currently recommended not to modify keys... Side effects may cause inconsitency. When the notification system will be implemented, it will be safer to do so.



status_t BICRegistry::GetKey(const key_id id, const key_attribute_id attribute, key_value value, size_t & size)

Retrieves the key id with the attribute id into value that can store size byte of string.

id [i] : id of the key. Mandatory
attribute [i] : attribute of the key. If no attribute, should be "".
value [o] : buffer to store value. It is enough long to stort size byte of a string (must be one char wider for the terminating NULL char). If it is not enough large, it contains "".
size [i/o] : size of the buffer (not counting terminating NULL char). The real size is returned...
returns BIC_BUFFER_TOO_SMALL is there is not enough room into the value buffer. BIC_KEY_NO_FOUND means that the key has NOT been found.



status_t BICRegistry::SetKey(const key_id id, const key_attribute_id attribute, const key_value value)

Changes the value of the key. It is recommanded not do so... <thread-safe access will come in the future>.

id [i] : id of the key. Mandatory
attribute [i] : attribute of the key. If no attribute, should be "".
value [o] : the string containing the value.



status_t BICRegistry::DeleteKey(const key_id id, const key_attribute_id attribute)

Deletes the key with id and attribute. Not recommended.

id [i] : id of the key. Mandatory
attribute [i] : attribute of the key. If no attribute, should be "".

Thread Safeness

Currently thread safe support is minimalist... It should be OK. Calling a registry function locks the registry automatically.



bool BICRegistry::Lock()
void BICRegistry::Unlock()
bool BICRegistry::IsLocked()

Lock and Unlock the BICRegistry for safe thread access.

IsLocked() checks for the state of the lock... See also BLock::Lock()

Music

Various coding inspiration by:

Megadeth, les Wampas, Led Zeppelin, Rage Against the Machine, SymphonyX, Angra, Jean-Michel Jarre, Metallica, Enigma, Eric Serra (the Fifth Element soundtrack), Blur, Marillion, Placebo, the Beatles, Pearl Jam, Oobik & the Pucks, Helloween and Iron Maiden.

Page maintained by Hubert Figuière - <hfiguiere@teaser.fr> - July 13th 1997.