File: gpgme.info,  Node: Checking for updates,  Prev: Using the Assuan protocol,  Up: Miscellaneous

7.7.3 How to check for software updates
---------------------------------------

The GnuPG Project operates a server to query the current versions of
software packages related to GnuPG. GPGME can be used to access this
online database and check whether a new version of a software package is
available.

 -- Data type: gpgme_query_swdb_result_t
     SINCE: 1.8.0

     This is a pointer to a structure used to store the result of a
     ‘gpgme_op_query_swdb’ operation.  After success full call to that
     function, you can retrieve the pointer to the result with
     ‘gpgme_op_query_swdb_result’.  The structure contains the following
     member:

     ‘name’
          This is the name of the package.

     ‘iversion’
          The currently installed version or an empty string.  This
          value is either a copy of the argument given to
          ‘gpgme_op_query_swdb’ or the version of the installed software
          as figured out by GPGME or GnuPG.

     ‘created’
          This gives the date the file with the list of version numbers
          has originally be created by the GnuPG project.

     ‘retrieved’
          This gives the date the file was downloaded.

     ‘warning’
          If this flag is set either an error has occurred or some of
          the information in this structure are not properly set.  For
          example if the version number of the installed software could
          not be figured out, the ‘update’ flag may not reflect a
          required update status.

     ‘update’
          If this flag is set an update of the software is available.

     ‘urgent’
          If this flag is set an available update is important.

     ‘noinfo’
          If this flag is set, no valid information could be retrieved.

     ‘unknown’
          If this flag is set the given ‘name’ is not known.

     ‘tooold’
          If this flag is set the available information is not fresh
          enough.

     ‘error’
          If this flag is set some other error has occurred.

     ‘version’
          The version string of the latest released version.

     ‘reldate’
          The release date of the latest released version.

 -- Function: gpgme_error_t gpgme_op_query_swdb (gpgme_ctx_t CTX,
          const char *NAME, const char *IVERSION, gpgme_data_t RESERVED)

     SINCE: 1.8.0

     Query the software version database for software package NAME and
     check against the installed version given by IVERSION.  If IVERSION
     is given as ‘NULL’ a check is only done if GPGME can figure out the
     version by itself (for example when using "gpgme" or "gnupg").  If
     ‘NULL’ is used for NAME the current gpgme version is checked.
     RESERVED must be set to 0.

 -- Function: gpgme_query_swdb_result_t gpgme_op_query_swdb_result
          (gpgme_ctx_t CTX)

     SINCE: 1.8.0

     The function ‘gpgme_op_query_swdb_result’ returns a
     ‘gpgme_query_swdb_result_t’ pointer to a structure holding the
     result of a ‘gpgme_op_query_swdb’ operation.  The pointer is only
     valid if the last operation on the context was a successful call to
     ‘gpgme_op_query_swdb’.  If that call failed, the result might be a
     ‘NULL’ pointer.  The returned pointer is only valid until the next
     operation is started on the context CTX.

Here is an example on how to check whether GnuPG is current:

     #include 

     int
     main (void)
     {
       gpg_error_t err;
       gpgme_ctx_t ctx;
       gpgme_query_swdb_result_t result;

       gpgme_check_version (NULL);
       err = gpgme_new (&ctx);
       if (err)
         fprintf (stderr, "error creating context: %s\n", gpg_strerror (err));
       else
         {
           gpgme_set_protocol (ctx, GPGME_PROTOCOL_GPGCONF);

           err = gpgme_op_query_swdb (ctx, "gnupg", NULL, 0);
           if (err)
             fprintf (stderr, "error querying swdb: %s\n", gpg_strerror (err));
           else
             {
               result = gpgme_op_query_swdb_result (ctx);
               if (!result)
                 fprintf (stderr, "error querying swdb\n");
               if (!result->warning && !result->update)
                 printf ("GnuPG version %s is current\n",
                         result->iversion);
               else if (!result->warning && result->update)
                 printf ("GnuPG version %s can be updated to %s\n",
                         result->iversion, result->version);
               else
                 fprintf (stderr, "error finding the update status\n");
             }
           gpgme_release (ctx);
         }
       return 0;
     }