hws.h #1

// Copyright 2015 Perforce Software Inc.
#ifndef __HELIX_WEB_SERVICES_H___
#define __HELIX_WEB_SERVICES_H___

#include "hws/Client.h"

/*! \mainpage Helix Web Services Client SDK for Qt

    \section usage Basic usage

    The primary interface for Helix Web Services involves the hws::Client.
    The hws::Client interacts with the server via several remote calls.
    Subsequently, using this API usually starts by attaching slots up to several signals.
    Then you setup a signal

    \code{.cpp}
    #include <hws.h>

    hws::Client client;

    // Each client should be tied to a particular Perforce Web Services instance.
    client.setUrl("http://p4_web_services.mycompany.com");

    connect(client, &hws::Client::logInDone,
            myObj, &MyObj::logInDone);

    connect(client, &hws::Client::executeMethodDone,
            myObj, &MyObj::executeMethodDone);

    client.logIn("myuser", "mypassword");

    // Some possible 'callback' handlers

    void MyObj::logInDone(RequestErrorPtr err, SessionPtr session)
    {
        // You should probably check for errors, and probably cache the session
        // here so you don't have to re-log in

        // Load all projects just for a fun starting point
        client.fetchProjects();
    }

    void MyObj::executeMethodDone(RequestErrorPtr err,
                                  const QString & method,
                                  const QString & path,
                                  const QSharedPointer<hws::Client::QVariantMapList> data)
    {
        // given the method and path, probably reformat and dispatch the
        // data to your application's handlers
    }
    \endcode

    Each hws::Client instance requires a Session.
    A session can be created by calling the `logIn` method, which will then store the session locally.
    (That Session instance can be stored locally and then, instead of calling `logIn`, you call `setSession`.)
    This session will be valid as long as the underlying Perforce server ticket allows.
    If you start to receive authentication errors, your client will have to log in again, and restore a new session.

    Authentication errors are returned with the code `RequestError::AUTHENTICATION_ERROR` of any `RequestError` returned by pretty much any server call.

 */;

namespace hws {

    // Semantic versioning information for the project.

    // Changes to the major version should indicate a breaking change to the API
    #define HELIX_WEB_SERVICES_MAJOR_VERSION 1

    // Changes to the minor version indicate most likely a feature addition,
    // but shouldn't break any existing code.
    #define HELIX_WEB_SERVICES_MINOR_VERSION 0

    // Patch versions shouldn't have any API change at all, just bug fixes.
    #define HELIX_WEB_SERVICES_PATCH_VERSION 0

    // If non-null, this is not an official release, and this string indicates
    // more information, like "main-[CHANGELIST]" that can be
    #define HELIX_WEB_SERVICES_PRERELEASE_VERSION "main-DEV"
}

#endif // __HELIX_WEB_SERVICES_H__