src/external/3rd/library/perforce/include/clientapi.h

   1 /*
   2  * Copyright 1995, 2000 Perforce Software.  All rights reserved.
   3  *
   4  * This file is part of Perforce - the FAST SCM System.
   5  */
   6
   7 # include "stdhdrs.h"
   8
   9 # include "strbuf.h"
  10 # include "strdict.h"
  11 # include "error.h"
  12 # include "handler.h"
  13
  14 # include "filesys.h"
  15
  16 # include "p4tags.h"
  17
  18 # include "clientmerge.h"
  19 # include "clientuser.h"
  20
  21 # include "keepalive.h"
  22
  23 /*
  24  * ClientApi - the Perforce client API
  25  *
  26  * Basic flow:
  27  *
  28  *      ClientUser ui;
  29  *      ClientApi client;
  30  *
  31  *      // SetPort(), SetProtocol() must happen _before_ the Init().
  32  *
  33  *      client.SetPort( somefunctionof( client.GetPort() ) ); //optional
  34  *      client.SetProtocol( "var", "value" ); //optional
  35  *
  36  *      client.Init( e );
  37  *
  38  *      // GetClient(), SetBreak(), SetProg() must happen _after_ the Init().
  39  *
  40  *      client.SetBreak( &k );      // optional
  41  *
  42  *      client.SetProg( "MyApp" );  // optional
  43  *
  44  *      client.SetClient( somefunctionof( client.GetClient() ) ); //optional
  45  *      client.SetCwd( somefunctionof( client.GetCwd() ) ); //optional
  46  *      client.SetUser( somefunctionof( client.GetUser() ) ); //optional
  47  *
  48  *      while( !client.Dropped() )
  49  *      {
  50  *          client.SetArgv( argc, argv )
  51  *          client.Run( func, &ui )
  52  *      }
  53  *
  54  *      return client.Final( e );
  55  *
  56  * Public methods:
  57  *
  58  *      ClientApi::SetUi() - reset the ClientUser object used
  59  *      ClientApi::SetProtocol() - ask for special server treatment
  60  *      ClientApi::GetProtocol() - get a protocol capability
  61  *              SetProtocol() is called before Init(); GetProtocol() after Run().
  62  *
  63  *      ClientApi::Init() - establish connection and prepare to run commands.
  64  *
  65  *      ClientApi::SetVar() - set variable
  66  *      ClientApi::SetVarV() - set variable using var=value syntax
  67  *      ClientApi::SetArgv() - set unnamed variables (args for Run())
  68  *      ClientApi::GetVar() - get variable
  69  *
  70  *      ClientApi::Run() - run a single command
  71  *      ClientApi::Final() - clean up end of connection, returning error count.
  72  *      ClientApi::Dropped() - check if connection is no longer serviceable
  73  *
  74  *      ClientApi::RunTag() - run a single command (potentially) asynchronously.
  75  *      ClientApi::WaitTag() - wait for a RunTag()/all RunTag()s to complete.
  76  *
  77  *      ClientApi::SetCharset()
  78  *      ClientApi::SetClient()
  79  *      ClientApi::SetCwd()
  80  *      ClientApi::SetHost()
  81  *      ClientApi::SetLanguage()
  82  *      ClientApi::SetPassword()
  83  *      ClientApi::SetPort()
  84  *      ClientApi::SetUser() - set client, current directory, host, port, or
  85  *              user, overridding all defaults.  SetPort() must be called
  86  *              before Init() in order to take effect.  The others must be
  87  *              set before Run() to take effect.
  88  *
  89  *              SetCwd() additionally searches for a new P4CONFIG file.
  90  *
  91  *      ClientApi::SetBreak() - set a subclassed KeepAlive object (only
  92  *              method IsAlive returns zero on dropped connection). Must
  93  *              be called after Init() it order to take affect.
  94  *
  95  *      ClientApi::SetProg() - set the name of the application program,
  96  *              this will show up in 'p4 monitor' and server log output.
  97  *              Must be called after Init() it order to take affect.
  98  *
  99  *      ClientApi::DefineCharset()
 100  *      ClientApi::DefineClient()
 101  *      ClientApi::DefineHost()
 102  *      ClientApi::DefineLanguage()
 103  *      ClientApi::DefinePassword()
 104  *      ClientApi::DefinePort()
 105  *      ClientApi::DefineUser() - sets client, port, or user in the registry
 106  *              and (so as to take permanent effect) then calls SetClient(),
 107  *              etc. to take immediate effect.
 108  *
 109  *      ClientApi::GetCharset()
 110  *      ClientApi::GetClient()
 111  *      ClientApi::GetCwd()
 112  *      ClientApi::GetHost()
 113  *      ClientApi::GetLanguage()
 114  *      ClientApi::GetOs()
 115  *      ClientApi::GetPassword()
 116  *      ClientApi::GetPort()
 117  *      ClientApi::GetUser() - get current directory, client, OS, port or user,
 118  *              as determined by defaults or by corresponding set value.
 119  *              GetClient()/GetHost() are not valid until after Init()
 120  *              establishes the connection, because the hostname of the
 121  *              local endpoint may serve as the default client name.
 122  *
 123  *      ClientApi::SetIgnorePassword() - This function ignores passwords
 124  *              that are found in the registry (NT), host environments or
 125  *              configuration files.  If this function is set then only
 126  *              passwords supplied through SetPassword() will be honored.
 127  *              Tickets continue to work as normal. Must be called before
 128  *              Init() in order to take affect.
 129  */
 130
 131 class Client;
 132
 133 class ClientApi : public StrDict {
 134
 135     public:
 136         // caller's main interface
 137
 138                         ClientApi();
 139                         ~ClientApi();
 140
 141         void            SetTrans( int output, int content = -2,
 142                                 int fnames = -2, int dialog = -2 );
 143
 144         void            SetProtocol( const char *p, const char *v );
 145         void            SetProtocolV( const char *p );
 146         StrPtr *        GetProtocol( const char *v );
 147
 148         void            Init( Error *e );
 149         void            Run( const char *func, ClientUser *ui );
 150         int             Final( Error *e );
 151         int             Dropped();
 152
 153         void            RunTag( const char *func, ClientUser *ui );
 154         void            WaitTag( ClientUser *ui = 0 );
 155
 156         void            SetCharset( const char *c );
 157         void            SetClient( const char *c );
 158         void            SetCwd( const char *c );
 159         void            SetHost( const char *c );
 160         void            SetLanguage( const char *c );
 161         void            SetPassword( const char *c );
 162         void            SetPort( const char *c );
 163         void            SetUser( const char *c );
 164         void            SetProg( const char *c );
 165
 166         void            SetCharset( const StrPtr *c );
 167         void            SetClient( const StrPtr *c );
 168         void            SetCwd( const StrPtr *c );
 169         void            SetHost( const StrPtr *c );
 170         void            SetLanguage( const StrPtr *c );
 171         void            SetPassword( const StrPtr *c );
 172         void            SetPort( const StrPtr *c );
 173         void            SetUser( const StrPtr *c );
 174         void            SetProg( const StrPtr *c );
 175
 176         void            SetBreak( KeepAlive *k );
 177
 178         void            DefineCharset( const char *c, Error *e );
 179         void            DefineClient( const char *c, Error *e );
 180         void            DefineHost( const char *c, Error *e );
 181         void            DefineLanguage( const char *c, Error *e );
 182         void            DefinePassword( const char *c, Error *e );
 183         void            DefinePort( const char *c, Error *e );
 184         void            DefineUser( const char *c, Error *e );
 185
 186         const StrPtr    &GetCharset();
 187         const StrPtr    &GetClient();
 188         const StrPtr    &GetCwd();
 189         const StrPtr    &GetHost();
 190         const StrPtr    &GetLanguage();
 191         const StrPtr    &GetOs();
 192         const StrPtr    &GetPassword();
 193         const StrPtr    &GetPort();
 194         const StrPtr    &GetUser();
 195
 196         void            SetIgnorePassword();
 197
 198     public:
 199         // The old interface, where ui was held from the start
 200
 201                         ClientApi( ClientUser *ui );
 202         void            SetUi( ClientUser *i );
 203         void            Run( const char *func );
 204
 205     private:
 206         // Our StrDict implementation
 207         // Set strdict.h for various GetVar/SetVar calls
 208
 209         StrPtr          *VGetVar( const StrPtr &var );
 210         void            VSetVar( const StrPtr &var, const StrPtr &val );
 211
 212     private:
 213         Client          *client;        // wrapped up RPC
 214         ClientUser      *ui;            // the old way
 215
 216 } ;