[Portland] Consistent messaging

[nf2]

Dan Kegel wrote:
> Looks good, except:
>
> I'd show a second line between the 'tools' and
> the desktop-specific implementations, emphasizing that
> the tools might not always use the comm link.
>
> I'd also change the text
> "Lubos Lunak, a key Portland Project developer responded
> immediately by pointing Jeremy to the code, "
> to
> "Lubos Lunak, a key Portland Project developer, responded
> immediately by pointing Jeremy to a prototype, "
>
> to avoid annointing any one prototype as "the" prototype.
>
>   
Yes - there are already two prototypes and perhaps there will be a third 
one using dbus.

Btw, my async "dapii" prototype is already working on the client side 
and i hope i can finish the daemon part next week.

Dapii is "Job-based" - a bit like KIO::Jobs and the idea is that there 
can be communication in between starting a job and the final "Reply" 
callback.
I have added sequence numbers to my messaging library, therefore 
parallel jobs over the same connection are possible.

This is how the protocol definition/client API/a  simple client would 
look like:

PROTOCOL DEFINITION ======================================================

JOB DownloadURL
  MSG_COMMAND 200
    ARG url string
    ARG localfile string
  ENDMSG
  MSG_BACK 202 Progress
    ARG bytecount int
    ARG progress int
    ARG mime string
  ENDMSG
  MSG_TO 203 Cancel
  ENDMSG
  MSG_REPLY 201
    ARG ok bool
  ENDMSG
ENDJOB


CLIENT SIDE API (autogenerated) ==========================================

/* DownloadURL */

typedef DapiRVal (*DapiDownloadURLProgressCallback) (DapiJob * job , 
void * userData , int bytecount, int progress, char * mime);

typedef DapiRVal (*DapiDownloadURLReplyCallback) (DapiJob * job, void * 
userData , DapiBool ok);

DapiRVal dapiDownloadURL(DapiHandle * dapiH , char * url, char * localfile,
      DapiDownloadURLProgressCallback cbDownloadURLProgress,
      DapiDownloadURLReplyCallback cbDownloadURLReply,
      void * userData,
      DapiJob ** job
);

DapiRVal dapiDownloadURLCancel(DapiJob * job );


SAMPLE CODE for a simple Client ==========================================

DapiRVal _handle_DapiDownloadURLProgressCallback(DapiJob * job , void * 
userData , int bytecount, int progress, char * mime) {
    ...
}

DapiRVal _handle_DapiDownloadURLReplyCallback(DapiJob * job, void * 
userData , DapiBool ok) {
    ...
}

int main() {

    DapiRVal rval;
    DapiJob * job1;
    ...
    DapiHandle * dapiH = dapi_handle_open();
    ...
    rval = dapiDownloadURL(dapiH , "xyz://file , "/tmp/localfile" ,
            _handle_DapiDownloadURLProgressCallback,
            _handle_DapiDownloadURLReplyCallback,
      NULL,
      &job1
    );
    ...
    while (!dapi_job_isFinished(job1)) {
        dapi_client_miniloop(dapiH); // basic main loop provided by 
dapii, or use glib/Qt main loop could be used as well.
    }
   
   
    dapi_job_unref(job1);
  
    dapi_handle_close(dapiH);

}

Regards,
Norbert