Hello fellow IM devs,<br><br>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:<br><br>*** 1. Hardcoded strings ***<br>
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:<br><br>typedef struct s_OtrlMessageAppOps {<br>
    OtrlPolicy (*policy)(void *opdata, ConnContext *context);<br>    ...<br>    void (*account_name_free)(void *opdata, const char *account_name);<br><br>    /* Handles an error given the error code */<br>    void (*handle_error)(void *opdata, ConnContext *context, OtrlErrorCode error_code);<br>
} OtrlMessageAppOps;<br><br><br>Tentatively, we will provide a convenient errorcode-to-errorstring lookup function that will look like this:<br><br>const char * otrl_message_errstr_en(OtrlErrorCode error_code);<br><br><br>
*** 2. Custom message stripping function ***<br>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.<br>
<br>gcry_error_t otrl_message_sending(OtrlUserState us,<br>    const OtrlMessageAppOps *ops,<br>    void *opdata, const char *accountname, const char *protocol,<br>    const char *recipient, const char *message, OtrlTLV *tlvs,<br>
    char **messagep,<br>    void (*add_appdata)(void *data, ConnContext *context),<br>    void *data,<br>    void (*convert_msg)(void *convertdata, char *source, char **target),<br>    void *convertdata);<br><br>int otrl_message_receiving(OtrlUserState us, const OtrlMessageAppOps *ops,<br>
    void *opdata, const char *accountname, const char *protocol,<br>    const char *sender, const char *message, char **newmessagep,<br>    OtrlTLV **tlvsp,<br>    void (*add_appdata)(void *data, ConnContext *context),<br>
    void *data,<br>    void (*convert_msg)(void *convertdata, char *source, char **target),<br>    void *convertdata);<br><br>*** 3. Fragmentation ***<br>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:<br>
<br><br>gcry_error_t otrl_message_sending(OtrlUserState us,<br>    const OtrlMessageAppOps *ops,<br>    void *opdata, const char *accountname, const char *protocol,<br>    const char *recipient, const char *message, OtrlTLV *tlvs,<br>
    char **messagep,<br>    void (*add_appdata)(void *data, ConnContext *context),<br>    void *data,<br>    void (*convert_msg)(void *convertdata, char *source, char **target),<br>    void *convertdata,<br>    OtrlFragmentPolicy fragPolicy);<br>
<br><br>Since we will not need to call otrl_message_fragment_and_send anymore, we are planning to remove that function from the public API.<br><br>*** 4. Stripping ConnContext ***<br>We are stripping down ConnContext so that it only exposes the members that are meant to be public. It will look like this:<br>
<br>typedef struct context {<br>    char * username;<br>    char * accountname;<br>    char * protocol;<br>    OtrlMessageState msgstate;<br>    OtrlAuthInfo auth;<br>    Fingerprint fingerprint_root;<br>    Fingerprint *active_fingerprint;<br>
    unsigned int protocol_version;<br>    void *app_data;<br>    void (*app_data_free)(void *);<br>    OtrlSMState *smstate;<br><br>    ConnContextInternal *internal_context;<br>} ConnContext;<br><br><br><br>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.<br>
<br>Cheers!<br>- willy<br><br><br>*** List of APIs to be kept in libotr4 ***<br>otrl_context_disconnect<br>otrl_context_find<br>otrl_context_find_fingerprint<br>otrl_context_forget_all<br>otrl_context_forget_fingerprint<br>
otrl_context_set_trust<br><br>otrl_message_abort_smp<br>otrl_message_disconnect<br>otrl_message_free<br>otrl_message_initiate_smp<br>otrl_message_initiate_smp_q<br>otrl_message_receiving<br>otrl_message_respond_smp<br>otrl_message_sending<br>
<br>otrl_privkey_fingerprint<br>otrl_privkey_forget_all<br>otrl_privkey_generate<br>otrl_privkey_generate_FILEp<br>otrl_privkey_hash_to_human<br>otrl_privkey_read<br>otrl_privkey_read_FILEp<br>otrl_privkey_read_fingerprints<br>
otrl_privkey_read_fingerprints_FILEp<br>otrl_privkey_write_fingerprints<br>otrl_privkey_write_fingerprints_FILEp<br><br>otrl_proto_default_query_msg<br>otrl_proto_message_type<br><br>otrl_tlv_find<br>otrl_tlv_free<br><br>
otrl_userstate_create<br>otrl_userstate_free <br>