<?xml version="1.0" encoding="UTF-8"?> <chapter version="5.0" xml:id="sdks.phoenix.qt" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"> <title>Qt SDK for Phoenix Services</title> <para> The Qt SDK for Phoenix Services provides source libraries for manipulating project metadata and notifications for Phoenix projects. </para> <section xml:id="sdks.phoenix.qt.overview"> <title>Basic usage</title> <para> The primary interface for Phoenix services involves the <code>PhoenixServicesClient</code>, which contains the main methods that interact with the server. Subsequently, using this API usually starts by attaching slots up to the main signals of this interface, then starting interaction. </para> <programlisting language="c++"> #include <phoenix.h> using namespace phoenix; PhoenixServicesClient client; // Each client should be tied to a particular Perforce Web Services instance. client.setUrl("http://p4_web_services.mycompany.com"); connect(client, &PhoenixServicesClient::logInDone, myObj, &MyObj::logInDone); connect(client, &PhoenixServicesClient::fetchProjectsDone, myObj, &MyObj::fetchProjectsDone); connect(client, &PhoenixServicesClient::fetchProjectDone, myObj, &MyObj::fetchProjectDone); connect(client, &PhoenixServicesClient::createProjectDone, myObj, &MyObj::createProjectDone); client.logIn("myuser", "mypassword"); 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::fetchProjectsDone(RequestErrorPtr err, PhoenixProjectListPtr projects) { qDebug() << "I have " << projects->size(); << " projects"; }</programlisting> <para> Each <code>PhoenixServicesClient</code> instance requires a <code>Session</code>. A session can be created by calling the <code>PhoenixServicesClient::logIn</code> method, which will then store the session locally. (That <code>Session</code> instance can be stored locally and then, instead of calling <code>PhoenixServicesClient::logIn</code>, you call <code>PhoenixServicesClient.setSession</code>.) This session will be valid as long as the underlying Perforce server ticket allows. If you start to receive unauthorized errors, your client will have to log in again, and restore a new session. </para> </section> <section xml:id="sdks.phoenix.qt.PhoenixServicesClient"> <title> <code>PhoenixServicesClient</code> reference </title> <simplesect xml:id="sdks.phoenix.qt.PhoenixServicesClient.methods"> <title>Methods</title> <informaltable> <tgroup cols="2"> <colspec colname="topic" colwidth="*"/> <colspec colname="description" colwidth="*"/> <thead> <row> <entry></entry> <entry> <para>Method</para> </entry> <entry> <para>Description</para> </entry> </row> </thead> <tbody> <row> <entry> <code>bool</code> </entry> <entry> <code>hasSession() const</code> </entry> <entry> When<code>true</code>, the client has an associated <code>Session</code> object, which it will use on the next slot call to the web server. Does not guarantee that the session has not expired. </entry> </row> <row> <entry> <code>const QString &</code> </entry> <entry> <code>phoenixPrefixPath() const</code> </entry> <entry> In some cases, you might have a special prefix where the Phoenix Web Services are deployed on the client, in which case you'd need to configure this path. </entry> </row> <row> <entry> <code>const Session & </code> </entry> <entry> <code>session() const</code> </entry> <entry> Returns the current <code>Session</code> instance. This might be an empty session that has no actual token values set, if you have not logged in or just set the session directly. </entry> </row> <row> <entry> <code>void</code> </entry> <entry> <code>setPhoenixPrefixPath(const QString & path);</code> </entry> <entry> Set the prefix path to the Phoenix web services instance. This is typically not needed, unless you mount the services to a different path on the server. Defaults to<code> /p4_phoenix_services/v1</code>. </entry> </row> <row> <entry> <code>void</code> </entry> <entry> <code>setSession(const Session & session)</code> </entry> <entry> Set the session instance on the client. Really only needs to be done when not using <code>logIn</code> to create the session. If you're calling<code>logIn</code>, this will be set automatically when successful. </entry> </row> <row> <entry> <code>void</code> </entry> <entry> <code>setUrl(const QUrl & url);</code> </entry> <entry> Set the Perforce Web Service URL. </entry> </row> <row> <entry> <code>const QUrl & </code> </entry> <entry> <code>url() const</code> </entry> <entry> The Perforce web services URL we should connect to. Should be set before making any request. </entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="sdks.phoenix.qt.PhoenixServicesClient.slots"> <title>Slots</title> <informaltable> <tgroup cols="2"> <colspec colname="topic" colwidth="*"/> <colspec colname="description" colwidth="*"/> <thead> <row> <entry></entry> <entry> <para>Slot</para> </entry> <entry> <para>Description</para> </entry> </row> </thead> <tbody> <row> <entry> <code>void</code> </entry> <entry> <code>createProject(const PhoenixProject & project)</code> </entry> <entry> Requests a new project be created on the server. At the moment, only the <code>name</code> property of the project should be set. The phoenix web services instance will decide other defaults as necessary. </entry> </row> <row> <entry> <code>void</code> </entry> <entry> <code>fetchProject(const QString & id)</code> </entry> <entry> Requests a single project from the server, based on it's<code> id</code>. <emphasis>This will likely include filtering in the future, when we've defined the workflow better. </emphasis> </entry> </row> <row> <entry> <code>void</code> </entry> <entry> <code>fetchProjects()</code> </entry> <entry> Requests the complete list of Phoenix projects to the server. <emphasis>This will likely include filtering in the future, when we've defined the workflow better. </emphasis> </entry> </row> <row> <entry> <code>void</code> </entry> <entry> <code>logIn(const QString & user, const QString & password) </code> </entry> <entry> Will attempt to log in as the user and password to the Perforce web services instance (configured as the URL property of the client). If successful, calls the <code>logInDone</code> signal, and, caches the <code>Session</code> instance locally. </entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="sdks.phoenix.qt.PhoenixServicesClient.signals"> <title>Signals</title> <informaltable> <tgroup cols="2"> <colspec colname="topic" colwidth="*"/> <colspec colname="description" colwidth="*"/> <thead> <row> <entry></entry> <entry> <para>Signal</para> </entry> <entry> <para>Description</para> </entry> </row> </thead> <tbody> <row> <entry> <code>void</code> </entry> <entry> <code>createProjectDone(RequestErrorPtr error)</code> </entry> <entry> When <code>error</code> is null, the project should exist in the system. </entry> </row> <row> <entry> <code>void</code> </entry> <entry> <code>fetchProjectDone(RequestErrorPtr error, PhoenixProjectPtr project) </code> </entry> <entry> Called on completion or failure of<code>fetchProject(id)</code>. If there's any problem, <code>error</code> will not be null, and you should not use the<code>project</code>. </entry> </row> <row> <entry> <code>void</code> </entry> <entry> <code>fetchProjectsDone(RequestErrorPtr error, PhoenixProjectListPtr projects) </code> </entry> <entry> Called on completion or failure of<code>fetchProjects()</code>. If there's any problem, <code>error</code> will not be null, and you should not use the<code>projects</code>. </entry> </row> <row> <entry> <code>void</code> </entry> <entry> <code>logInDone(RequestErrorPtr error, SessionPtr session) </code> </entry> <entry> Called on success or failure of the <code>logIn(user, password)</code> slot. If there's any problem, <code>error</code> will not be null, and you should not use the<code>session</code>. </entry> </row> </tbody> </tgroup> </informaltable> </simplesect> </section> </chapter>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#4 | 13972 | tjuricek |
Removing old microservice implementations. The system is now mostly a monolith. Eventually there will be a websocket service. |
||
#3 | 13460 | tjuricek |
Call out authentication problems with a specific application error code. This allows Qt clients to easily know when they should recreate a new session. |
||
#2 | 13459 | tjuricek |
Return the created project when creating a new project, since default values will often be filled out. Allow new projects to be created only with names set. We'll generate an ID at the moment, when I have better indexing, I'll double check for uniqueness. |
||
#1 | 13458 | tjuricek |
Revising P4 Web API docbook documentation to become the Perforce Web Services guide. Right now this is just focused on the Qt SDK. The remaining protocol documentation, etc, will happen eventually. |