williamr@4: // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@4: // All rights reserved. williamr@4: // This component and the accompanying materials are made available williamr@4: // under the terms of "Eclipse Public License v1.0" williamr@4: // which accompanies this distribution, and is available williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@4: // williamr@4: // Initial Contributors: williamr@4: // Nokia Corporation - initial contribution. williamr@4: // williamr@4: // Contributors: williamr@4: // williamr@4: // Description: williamr@4: // ULogger Client API header williamr@4: // williamr@4: // williamr@4: williamr@4: /** williamr@4: @file williamr@4: @publishedPartner williamr@4: @prototype williamr@4: */ williamr@4: williamr@4: #ifndef ULOGGERCLIENT_H williamr@4: #define ULOGGERCLIENT_H williamr@4: williamr@4: #include // RSessionBase williamr@4: #include williamr@4: #include "uloggerdatatypes.h" williamr@4: williamr@4: namespace Ulogger williamr@4: { williamr@4: williamr@4: /** williamr@4: Client-side session to the ULogger server. williamr@4: This class should be used to configure ULogger server. williamr@4: */ williamr@4: class RULogger : public RSessionBase williamr@4: { williamr@4: williamr@4: public: williamr@4: /* williamr@4: Default constructor. williamr@4: */ williamr@4: IMPORT_C RULogger(); williamr@4: williamr@4: /* williamr@4: Default destructor. williamr@4: Closes the client session. williamr@4: */ williamr@4: IMPORT_C ~RULogger(); williamr@4: williamr@4: /** williamr@4: Connects a client to the ULogger server. williamr@4: If the server isn't already running it will be started. williamr@4: To end the server session, use Close(). williamr@4: williamr@4: @return KErrNone, if successful, otherwise one of the other system-wide williamr@4: error codes returned by RProcess:Create() or williamr@4: RSessionBase::CreateSession(). williamr@4: */ williamr@4: IMPORT_C TInt Connect(); williamr@4: williamr@4: /** williamr@4: Not yet supported, does nothing and returns KErrNotSupported. williamr@4: williamr@4: Starts/stops running ULogger as a service. Running ULogger as a service williamr@4: means that ULogger is always active in the background, which is necessary williamr@4: if the objective is to connect to ULogger from a remote machine, so that williamr@4: ULogger is then listening for remote connections. williamr@4: If ULogger is not running as a service, it is only active when it is williamr@4: handling a client request or it is currenty logging traces (i.e. the Start() williamr@4: function was called). williamr@4: williamr@4: @param aRunAsService The flag to indicate whether the server should run as a williamr@4: service or not williamr@4: @return KErrNotSupported, as this function is not yet implemented in the server. williamr@4: */ williamr@4: IMPORT_C TInt RunAsService(TBool aRunAsService); williamr@4: williamr@4: /** williamr@4: Starts outputting trace packets. williamr@4: Pre-requisite: This will only output trace packets containing filter identifers that williamr@4: match enabled filters. Use SetPrimaryFiltersEnabled(), SetSecondaryFiltersEnabled() and williamr@4: SetSecondaryFilteringEnabled() to enable the relevant filters. williamr@4: williamr@4: @return KErrNone, if sending the Start message to the server was successful; williamr@4: KErrCorrupt, if the ULogger configuration file is corrupt; williamr@4: KErrServerTerminated, if the server is no longer present; williamr@4: KErrServerBusy, if there are no message slots available; williamr@4: KErrNoMemory, if there is insufficient memory available; williamr@4: KErrInUse, if server was started previously; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt Start(); williamr@4: williamr@4: /** williamr@4: Stops outputting trace packets. williamr@4: williamr@4: @return KErrNone, if sending the Stop message to the server was successful; williamr@4: KErrServerTerminated, if the server is no longer present; williamr@4: KErrServerBusy, if there are no message slots available; williamr@4: KErrNoMemory, if there is insufficient memory available; williamr@4: KErrNotReady, if ULogger wasn't started previously. williamr@4: */ williamr@4: IMPORT_C TInt Stop(); williamr@4: williamr@4: /** williamr@4: Restarts server. williamr@4: williamr@4: @return KErrNone, if sending the Restart message to the server was successful; williamr@4: KErrCorrupt, if the ULogger configuration file is corrupt; williamr@4: KErrServerTerminated, if the server is no longer present; williamr@4: KErrServerBusy, if there are no message slots available; williamr@4: KErrNoMemory, if there is insufficient memory available; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt Restart(); williamr@4: williamr@4: /** williamr@4: Enables/disables the specified primary filters. williamr@4: This allows output of trace packets containing primary filter identifiers that match the williamr@4: enabled primary filters. williamr@4: Note: If a trace packet contains a secondary filter identifier, and secondary filtering is williamr@4: enabled, the matching secondary filter must also be enabled to allow this packet to be output. williamr@4: williamr@4: @param aFilters The primary filters to enable/disable williamr@4: @param aEnabled The boolean to specify the action. ETrue to enable and EFalse to disable. williamr@4: @return KErrNone, if sending the SetPrimaryFiltersEnabled message to the williamr@4: server was successful; williamr@4: KErrArgument, if the specified array of filters contains more than williamr@4: KMaxPrimaryFiltersLimit elements or the array is empty; williamr@4: KErrCorrupt, if the ULogger configuration file is corrupt; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt SetPrimaryFiltersEnabled(const CArrayFixFlat& aFilters, TBool aEnabled); williamr@4: williamr@4: /** williamr@4: Gets all enabled primary filters. williamr@4: williamr@4: @param aFilters The array to be populated with enabled filters williamr@4: @return KErrNone, if sending the PrimaryFiltersEnabled message to the williamr@4: server was successful; williamr@4: KErrCorrupt, if the ULogger configuration file is corrupt; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetPrimaryFiltersEnabled(CArrayFixFlat& aFilters); williamr@4: williamr@4: /** williamr@4: Enables/disables the specified secondary filters. williamr@4: This allows output of trace packets containing secondary filter identifiers that match the williamr@4: enabled secondary filters. williamr@4: Note1: Secondary filters are only relevant when secondary filtering is williamr@4: enabled (see SetSecondaryFilteringEnabled()). If secondary filtering williamr@4: is disabled, trace packets are logged regardless of any secondary filter identifiers. williamr@4: Note2: Enabling secondary filters will automatically enable secondary filtering. williamr@4: Note3: Primary filtering is always enabled and therefore there is no williamr@4: equivalent method for enabling/disabling primary filtering. williamr@4: williamr@4: @param aFilters The secondary filters to enable/disable williamr@4: @param aEnabled The boolean to specify the action. ETrue to enable and EFalse to disable. williamr@4: @return KErrNone, if sending the SetSecondaryFiltersEnabled message to the williamr@4: server was successful; williamr@4: KErrArgument, if the specified array of filters contains more than williamr@4: KMaxSecondaryFiltersLimit elements, the array is empty or williamr@4: number of currently set filters plus number of elements in aFilters array williamr@4: is greather than KMaxSecondaryFiltersLimit; williamr@4: KErrCorrupt, if the ULogger configuration file is corrupt; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt SetSecondaryFiltersEnabled(const RArray& aFilters, TBool aEnabled); williamr@4: williamr@4: /** williamr@4: Gets all enabled secondary filters. williamr@4: williamr@4: @param aFilters The array to be populated with enabled filters williamr@4: @return KErrNone, if sending the SecondaryFiltersEnabled message to the williamr@4: server was successful; williamr@4: KErrNoMemory, if there is insufficient memory available; williamr@4: KErrCorrupt, if the ULogger configuration file is corrupt; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetSecondaryFiltersEnabled(RArray& aFilters); williamr@4: williamr@4: /** williamr@4: Enables/disables filtering on secondary filters. williamr@4: When secondary filtering is enabled, only those trace packets containing a williamr@4: secondary filter identifier matching an enabled secondary filter are output williamr@4: (see SetSecondaryFiltersEnabled()). Note that trace packets must also contain williamr@4: a primary filter identifier matching an enabled primary filter in order to be output williamr@4: (see SetPrimaryFilterEnabled()). williamr@4: williamr@4: @param aEnabled The boolean to specify the action. ETrue to enable and EFalse to disable. williamr@4: @return KErrNone, if sending the SetSecondaryFilteringEnabled message to the williamr@4: server was successful; williamr@4: KErrCorrupt, if the ULogger configuration file is corrupt; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt SetSecondaryFilteringEnabled(TBool aEnabled); williamr@4: williamr@4: /** williamr@4: Gets secondary filtering enabled value. williamr@4: williamr@4: @param aEnabled The boolean to be populated with the secondary filtering enabled value williamr@4: @return KErrNone, if sending the SecondaryFilteringEnabled message to the williamr@4: server was successful; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetSecondaryFilteringEnabled(TBool& aEnabled); williamr@4: williamr@4: /** williamr@4: Sets which output plug-in is to be used for outputting trace packets. williamr@4: The plug-in that is passed to this method needs to be one of the williamr@4: plug-ins reported by InstalledOutputPlugins(); williamr@4: williamr@4: @param aPluginName The name of the plug-in to be used, needs to be one of williamr@4: the names returned by InstalledOutputPlugins() williamr@4: @return KErrNone, if sending the SetActiveOutputPlugin message to the server williamr@4: was successful; williamr@4: KErrAlreadyExists, if aPluginName value was previously set; williamr@4: KErrNotFound, if aPluginName does not match the name of an existing Ulogger output plug-in; williamr@4: KErrNoMemory, if there is insufficient memory available; williamr@4: KErrArgument, if passed descriptor is empty; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt ActivateOutputPlugin(const TDesC8& aPluginName); williamr@4: williamr@4: /** williamr@4: Gets the active output plug-in. williamr@4: williamr@4: @param aPluginName The 8-bit descriptor to be populated with the name of williamr@4: the active output plug-in (max length: KMaxPath). williamr@4: @return KErrNone, if sending the ActiveOutputPlugin message to the williamr@4: server was successful; williamr@4: KErrOverflow, if the passed-in descriptor is smaller than the length williamr@4: of the plug-in name; williamr@4: KErrNotFound, if no output plug-in has been set; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetActiveOutputPlugin(TDes8& aPluginName); williamr@4: williamr@4: /** williamr@4: Gets all the installed output plug-ins. williamr@4: williamr@4: @param aPluginNames The array to be populated with the installed plug-in filename and plug-in names. williamr@4: @return KErrNone, if sending the InstalledOutputPlugins message to the williamr@4: server was successful; williamr@4: KErrNoMemory, if there is insufficient memory available; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetInstalledOutputPlugins(CArrayPtrFlat& aPluginNames); williamr@4: williamr@4: /** williamr@4: Sets which input plug-in is to be used for sending messages to ULogger from a williamr@4: remote machine. This is only relevant for the remote control functionality williamr@4: of ULogger, which allows a remote machine to control the operation of williamr@4: ULogger, instead of a client on the device using RULogger. williamr@4: The plug-in that is passed to this method needs to be one of the williamr@4: plug-ins reported by GetInstalledInputPlugins. williamr@4: williamr@4: @param aPluginName The name of the input plug-in to be activated. williamr@4: @return KErrNone, if sending the SetActiveInputPlugin message to the server williamr@4: was successful; williamr@4: KErrAlreadyExists, if aPluginName value was previously set; williamr@4: KErrNotFound, if aPluginName does not match the name of an existing Ulogger input plug-in; williamr@4: KErrNoMemory, if there is insufficient memory available; williamr@4: KErrArgument, if passed descriptor is empty; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt ActivateInputPlugin(const TDesC8& aPluginName); williamr@4: williamr@4: /** williamr@4: Gets the active input plug-in. williamr@4: williamr@4: @param aPluginName The 8-bit descriptor to be populated with the name of williamr@4: the active plug-in (max length: KMaxPath). williamr@4: @return KErrNone, if sending the ActiveInputPlugin message to the williamr@4: server was successful; williamr@4: KErrOverflow, if the passed-in descriptor is smaller than the length williamr@4: of the plug-in name; williamr@4: KErrNotFound, if no input plug-in has been set; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetActiveInputPlugin(TDes8& aPluginName); williamr@4: williamr@4: /** williamr@4: Deactivates the currently active input plug-in. williamr@4: williamr@4: @return KErrNone, if sending the DeActivateInputPlugin message to the server williamr@4: was successful; williamr@4: KErrNotFound, if no input plug-in has been set; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt DeActivateInputPlugin(); williamr@4: williamr@4: /** williamr@4: Gets all installed input plug-ins. williamr@4: williamr@4: @param aPluginNames The array to be populated with the installed input plug-in names. williamr@4: @return KErrNone, if sending the GetInstalledInputPlugins message to the williamr@4: server was successful; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetInstalledInputPlugins(CArrayPtrFlat& aPluginNames); williamr@4: williamr@4: /** williamr@4: Adds a configuration to a plug-in (output or input). This is specific to the plug-in. williamr@4: williamr@4: Example1: aPluginName="uloggerfileplugin", aConfiguration.SetKey("output_path"), aConfiguration.SetValue(_L("c:\\logs\\ulogger\\tracelogs.btl")) williamr@4: Example2: aPluginName="uloggerserialplugin", aConfiguration.SetKey("baudrate") , aConfiguration.SetValue("115200") williamr@4: williamr@4: @param aPluginName The plug-in name (without the .dll extension) williamr@4: @param aConfiguration TPluginConfiguration (key-value type configuration) williamr@4: @return KErrNone, if sending the SetPluginConfigurations message to the williamr@4: server was successful; williamr@4: KErrNotFound, if aPluginName does not match the name of an existing ULogger plug-in (output or input); williamr@4: KErrArgument, if aPluginName is an empty descriptor; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt SetPluginConfigurations(const TDesC8& aPluginName, const TPluginConfiguration& aConfiguration); williamr@4: williamr@4: /** williamr@4: Gets all configurationas for the specified plug-in (output or input). williamr@4: williamr@4: @param aPluginName The name of the plug-in. This is mapped to the plug-in williamr@4: file name, it can be retrieved by calling williamr@4: GetInstalledOutputPlugins and GetInstalledInputPlugins williamr@4: @param aConfigurations The array that is to be populated with plug-in williamr@4: configuration items. Ownership of any objects williamr@4: appended to this array is passed to the caller. williamr@4: @return KErrNone, if sending the PluginConfigurations message to the williamr@4: server was successful; williamr@4: KErrNotFound, if aPluginName does not match the name of an existing ULogger plug-in (output or input); williamr@4: KErrArgument, if aPluginName is an empty descriptor; williamr@4: otherwise one of the other system-wide error codes. williamr@4: williamr@4: */ williamr@4: IMPORT_C TInt GetPluginConfigurations(const TDesC8& aPluginName, RPointerArray& aConfigurations); williamr@4: williamr@4: /** williamr@4: Removes all the configurations of the specified plug-in williamr@4: williamr@4: @param aPluginName The plug-in name whose settings are to be removed williamr@4: @return KErrNone, if sending the RemovePluginConfigurations message to the williamr@4: server was successful; williamr@4: KErrNotFound, if aPluginName does not match the name of an existing ULogger plug-in (output or input) williamr@4: or the plug-in had no settings; williamr@4: KErrArgument, if aPluginName is an empty descriptor; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt RemovePluginConfigurations(const TDesC8& aPluginName); williamr@4: williamr@4: /** williamr@4: Sets the size of the trace buffer, specified in KB (default: 1024KB). williamr@4: The trace buffer is the buffer that UTrace uses to hold the trace packets williamr@4: before they are output (using the currently active output plug-in). williamr@4: See also the documentation of SetNotificationSize(). williamr@4: williamr@4: @param aSize The desired new trace buffer size in KB williamr@4: @return KErrNone, if sending the SetBufferSize message to the server was williamr@4: successful; williamr@4: KErrArgument, if aSize value is not in range [1-1024]; williamr@4: KErrGeneral, if aSize value is smaller than data notification size; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt SetBufferSize(TInt aSize); williamr@4: williamr@4: /** williamr@4: Gets the size of the trace buffer in KB. williamr@4: See SetBufferSize() for an explanation of the trace buffer size. williamr@4: williamr@4: @param aSize The TInt to be populated with the trace buffer size in KB. williamr@4: @return KErrNone, if sending the BufferSize message to the server was williamr@4: successful; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetBufferSize(TInt& aSize); williamr@4: williamr@4: /** williamr@4: Sets the data notification size, specified in KB (default: 512KB). williamr@4: The data notification size is a threshold on the trace buffer usage, above williamr@4: which the trace buffer is flushed, i.e. all the trace packets in the trace buffer williamr@4: are output using the active output plug-in. williamr@4: See also the documentation of SetBufferSize(). williamr@4: williamr@4: @param aSize The desired new data notification size in KB williamr@4: @return KErrNone, if sending the SetNotificationSize message to the server williamr@4: was successful; williamr@4: KErrArgument, if aSize value is not in range [0-1024]; williamr@4: KErrGeneral, if aSize value is greater than trace buffer size; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt SetNotificationSize(TInt aSize); williamr@4: williamr@4: /** williamr@4: Gets the data notification size. williamr@4: See SetNotificationSize() for an explanation of the data notification size. williamr@4: williamr@4: @param aSize The TInt to be populated with the data notification size in KB. williamr@4: @return KErrNone, if sending the NotificationSize message to the server was williamr@4: successful; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetNotificationSize(TInt& aSize); williamr@4: williamr@4: /** williamr@4: Sets the trace buffer mode. williamr@4: williamr@4: @param aMode The buffer mode: 1 if Straight williamr@4: 0 if Circular williamr@4: @return KErrNone, if sending the SetBufferMode message to the server was williamr@4: successful; williamr@4: KErrArgument, if the specified mode is not one of 0 or 1; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt SetBufferMode(TInt aMode); williamr@4: williamr@4: /** williamr@4: Gets the trace buffer mode. williamr@4: williamr@4: @param aMode The TInt to be populated with the buffer mode: 1 if Straight williamr@4: 0 if Circular williamr@4: @return KErrNone, if sending the BufferMode message to the server was williamr@4: successful; williamr@4: otherwise one of the other system-wide error codes. williamr@4: */ williamr@4: IMPORT_C TInt GetBufferMode(TInt& aMode); williamr@4: williamr@4: /** williamr@4: Gets the client side version number. williamr@4: williamr@4: @return The client side version number. williamr@4: */ williamr@4: IMPORT_C TVersion Version(); williamr@4: williamr@4: private: williamr@4: TInt StartServer(); williamr@4: williamr@4: private: williamr@4: TUint32 iReserved1; // For future BC williamr@4: TUint32 iReserved2; // For future BC williamr@4: }; williamr@4: williamr@4: } // namespace williamr@4: williamr@4: #endif // ULOGGERCLIENT_H