[OTR-dev] Requirements for libotr4

[Willy Lew]

Hello fellow IM devs,

As some of you may already know, we are revamping the libotr API (the
messaging part in particular) to address several issues that were brought up
recently. The four major changes are:

*** 1. Hardcoded strings ***
No more hardcoded HTML error strings! We are adding a new function in
OtrlMessageAppOps to let the IM handle the error according to an error code.
For instance, OtrlMessageAppOps will look like this:

typedef struct s_OtrlMessageAppOps {
    OtrlPolicy (*policy)(void *opdata, ConnContext *context);
    ...
    void (*account_name_free)(void *opdata, const char *account_name);

    /* Handles an error given the error code */
    void (*handle_error)(void *opdata, ConnContext *context, OtrlErrorCode
error_code);
} OtrlMessageAppOps;


Tentatively, we will provide a convenient errorcode-to-errorstring lookup
function that will look like this:

const char * otrl_message_errstr_en(OtrlErrorCode error_code);


*** 2. Custom message stripping function ***
otrl_message_sending and otrl_message_receiving will be having an extra
optional argument (a callback function) to give the IMs the flexibility to
strip/convert the messages that are sent/received. For example, the
conversion function could strip the HTML tags out of the original message in
order to be guaranteed an HTML-free message.

gcry_error_t otrl_message_sending(OtrlUserState us,
    const OtrlMessageAppOps *ops,
    void *opdata, const char *accountname, const char *protocol,
    const char *recipient, const char *message, OtrlTLV *tlvs,
    char **messagep,
    void (*add_appdata)(void *data, ConnContext *context),
    void *data,
    void (*convert_msg)(void *convertdata, char *source, char **target),
    void *convertdata);

int otrl_message_receiving(OtrlUserState us, const OtrlMessageAppOps *ops,
    void *opdata, const char *accountname, const char *protocol,
    const char *sender, const char *message, char **newmessagep,
    OtrlTLV **tlvsp,
    void (*add_appdata)(void *data, ConnContext *context),
    void *data,
    void (*convert_msg)(void *convertdata, char *source, char **target),
    void *convertdata);

*** 3. Fragmentation ***
We are adding a new argument (OtrlFragmentPolicy) to otrl_message_sending so
that the fragmentation task is done without manually calling
otrl_message_fragment_and_send. If the original messaging behaviour is
preferred, the OtrlFragmentPolicy can be OTRL_FRAGMENT_DONTFRAGMENT. The new
signature for otrl_message_sending (including the conversion function as
described above) will look like this:


gcry_error_t otrl_message_sending(OtrlUserState us,
    const OtrlMessageAppOps *ops,
    void *opdata, const char *accountname, const char *protocol,
    const char *recipient, const char *message, OtrlTLV *tlvs,
    char **messagep,
    void (*add_appdata)(void *data, ConnContext *context),
    void *data,
    void (*convert_msg)(void *convertdata, char *source, char **target),
    void *convertdata,
    OtrlFragmentPolicy fragPolicy);


Since we will not need to call otrl_message_fragment_and_send anymore, we
are planning to remove that function from the public API.

*** 4. Stripping ConnContext ***
We are stripping down ConnContext so that it only exposes the members that
are meant to be public. It will look like this:

typedef struct context {
    char * username;
    char * accountname;
    char * protocol;
    OtrlMessageState msgstate;
    OtrlAuthInfo auth;
    Fingerprint fingerprint_root;
    Fingerprint *active_fingerprint;
    unsigned int protocol_version;
    void *app_data;
    void (*app_data_free)(void *);
    OtrlSMState *smstate;

    ConnContextInternal *internal_context;
} ConnContext;



At the end of this email you will find a list of APIs that will be kept
public. I have made that list by going through the code of a few IMs that
use OTR and by recording their respective otrl_* calls. If I have missed
anything in that list or if you have any other concerns/issues, please let
me know asap since I am in the process of gathering the requirements for the
new API. Note that we are also fixing the multiple login problem and this
entails a few other changes to the API but those have not been finalized
yet.

Cheers!
- willy


*** List of APIs to be kept in libotr4 ***
otrl_context_disconnect
otrl_context_find
otrl_context_find_fingerprint
otrl_context_forget_all
otrl_context_forget_fingerprint
otrl_context_set_trust

otrl_message_abort_smp
otrl_message_disconnect
otrl_message_free
otrl_message_initiate_smp
otrl_message_initiate_smp_q
otrl_message_receiving
otrl_message_respond_smp
otrl_message_sending

otrl_privkey_fingerprint
otrl_privkey_forget_all
otrl_privkey_generate
otrl_privkey_generate_FILEp
otrl_privkey_hash_to_human
otrl_privkey_read
otrl_privkey_read_FILEp
otrl_privkey_read_fingerprints
otrl_privkey_read_fingerprints_FILEp
otrl_privkey_write_fingerprints
otrl_privkey_write_fingerprints_FILEp

otrl_proto_default_query_msg
otrl_proto_message_type

otrl_tlv_find
otrl_tlv_free

otrl_userstate_create
otrl_userstate_free
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cypherpunks.ca/pipermail/otr-dev/attachments/20080617/460c4b90/attachment.html>