Converting the XPA API to 2.0

## XPAConvert: Converting the XPA API to 2.0

## Summary

This document describes tips for converting from xpa 1.0 (Xt-based xpa) to xpa 2.0 (socket-based xpa).

## Description

The following are tips for converting from xpa 1.0 (Xt-based xpa) to xpa 2.0 (socket-based xpa). The changes are straight-forward and almost can be done automatically (we used editor macros for most of the conversion).

- The existence of the cpp XPA_VERSION directive to distinguish between 1.0 (where it is not defined) and 2.0 (where it is defined).

- Remove the first widget argument from all send and receive server callbacks. Also change first 2 arguments from XtPointer to void *. For example:

      #ifdef XPA_VERSION
      static void XPAReceiveFile(client_data, call_data, paramlist, buf, len)
           void *client_data;
           void *call_data;
           char *paramlist;
           char *buf;
           int len;
      #else
      static void XPAReceiveFile(w, client_data, call_data, paramlist, buf, len)
           Widget w;
           XtPointer client_data;
           XtPointer call_data;
           char *paramlist;
           char *buf;
           int len;
      #endif

- Server callbacks should be declared as returning int instead of void. They now should return 0 for no errors, -1 for error.

- The mode flags have changed when defining XPA server callbacks. The old S flag (save buffer) is replaced by freebuf=false. The old E flag (empty buffer is OK) is no longer used (it was an artifact of the X implementation).

- Change NewXPACommand() to XPAcmdNew(), with the new calling sequence:

        xpa = NewXPACommand(toplevel, NULL, prefix, NULL);

  is changed to:

        xpa = XPACmdNew(xclass, name);

- Change the AddXPACommand() subroutine name to XPACmdAdd (with the same calling sequence):

        AddXPACommand(xpa, "file",
          "\tdisplay a new file\n\t\t  requires: filename",
          NULL, NULL, NULL, XPAReceiveFile, text, NULL);

  is changed to:

        XPACmdAdd(xpa, "file",
          "\tdisplay a new file\n\t\t  requires: filename",
          NULL, NULL, NULL, XPAReceiveFile, text, NULL);

- The XPAXtAppInput() routine should be called just before XtAppMainLoop() to add xpa fds to the Xt event loop:

        /* add the xpas to the Xt loop */
        XPAXtAddInput(app, NULL);

        /* process events */
        XtAppMainLoop(app);

- Change NewXPA() to XPANew() and call XPAXtAddInput() if the XtAppMainLoop routine already has been entered:

        xpa = NewXPA(saotng->xim->toplevel, prefix, xparoot,
                     "FITS data or image filename\n\t\t  options: file type",
                     XPASendData, new, NULL,
                     XPAReceiveData, new, "SE");

  is changed to:

        sprintf(tbuf, "%s.%s", prefix, xparoot);
        xpa = XPANew("SAOTNG", tbuf,
                     "FITS data or image filename\n\t\t  options: file type",
                     XPASendData, new, NULL,
                     XPAReceiveData, new, "SE");
        XPAXtAddInput(XtWidgetToApplicationContext(saotng->xim->toplevel), xpa);

- Change XPAInternalReceiveCommand() to XPACmdInternalReceive() remove first argument in the calling sequence):

        XPAInternalReceiveCommand(im->saotng->xim->toplevel,
      			    im->saotng, im->saotng->commands,
      			    "zoom reset", NULL, 0);

  is changed to:

        XPACmdInternalReceive(im->saotng, im->saotng->commands,
      			"zoom reset", NULL, 0);

- Change DestroyXPA to XPAFree:

        DestroyXPA(im->dataxpa);

  is changed to:

        XPAFree(im->dataxpa);

Go to XPA Help Index

##### Last updated: September 10, 2003