//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
*
* @final This class is not intended for extension.
*
- * The %DataControlProviderManager class manages the data control provider.
+ * The %DataControlProviderManager class helps a data control provider application to handle data control requests from other applications, and to send results or error messages for each data control operation.
*/
class _OSP_EXPORT_ DataControlProviderManager
: public Tizen::Base::Object
public:
/**
- * Sets a SQL-type data control provider listener to the data control provider manager. @n
- * The listener gets notified when a data control request is received from the other applications.
+ * Sets an SQL-friendly interface based data control provider listener for the data control provider manager. @n
+ * The listener gets notified when a data control request is received from other applications.
* To unset the listener, pass a @c null value to the listener parameter.
*
* @since 2.0
*
* @return An error code
- * @param[in] pListener The SQL-type data control provider listener @n
+ * @param[in] pListener The SQL-friendly interface based data control provider listener @n
* The listener must implement the ISqlDataControlProviderEventListener interface.
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_STATE This instance has not been properly constructed.
- * @exception E_INVALID_OPERATION The listener must be set for a service application.
+ * @exception E_INVALID_OPERATION The listener has not been set for a service application.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks This method must be called in App::OnAppInitializing() for setting the data control provider listener
+ * @remarks This method must be called by the App::OnAppInitializing() method for setting the data control provider listener
* before receiving the data control request.
*/
result SetSqlDataControlProviderEventListener(ISqlDataControlProviderEventListener* pListener);
/**
- * Sets a MAP-type data control provider listener to the data control provider manager. @n
- * The listener gets notified when a data control request is received from the other applications.
+ * Sets a key-value structured data control provider listener for the data control provider manager. @n
+ * The listener gets notified when a data control request is received from other applications.
* To unset the listener, pass a @c null value to the listener parameter.
*
* @since 2.0
*
* @return An error code
- * @param[in] pListener The MAP-type data control provider listener @n
+ * @param[in] pListener The key-value structured data control provider listener @n
* The listener must implement the IMapDataControlProviderEventListener interface.
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_STATE This instance has not been properly constructed.
- * @exception E_INVALID_OPERATION The listener must be set for a service application.
+ * @exception E_INVALID_OPERATION The listener has not been set for a service application.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks This method must be called in App::OnAppInitializing() for setting the data control provider listener
+ * @remarks This method must be called by the App::OnAppInitializing() method for setting the data control provider listener
* before receiving the data control request.
*/
result SetMapDataControlProviderEventListener(IMapDataControlProviderEventListener* pListener);
/**
- * Sends the success result and the result set of SELECT request to the application requesting the SQL-type
+ * Sends the success result and the result set of the SELECT request to the application requesting for the SQL-friendly interface based
* data control. @n
* The data control provider must call the %SendSqlDataControlSelectResult() method to notify success to the requesting application.
* The application requesting the data control can get the success result and the result set
* @param[in] pDbEnum The Tizen::Io::DbEnumerator instance to obtain the result set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG Either of the following conditions has occurred:
- * - This method cannot send result for the specified @c reqId of INSERT, UPDATE, or DELETE requests.
- * - Tizen::Io::Database or Tizen::Io::DbStatement instance associated with the specified @c pDbEnum is deleted.
- * @exception E_OBJ_NOT_FOUND The data control request specified with the @c reqId did not exist.
- * @exception E_OBJECT_LOCKED The database instance associated to the specified @c pDbEnum is locked.
- * @exception E_INVALID_FORMAT The database file associated to the specified @c pDbEnum is malformed.
+ * - The result for the specified @c reqId of the INSERT, UPDATE, or DELETE request cannot be sent.
+ * - The Tizen::Io::Database or Tizen::Io::DbStatement instance associated with the specified @c pDbEnum is deleted.
+ * @exception E_OBJ_NOT_FOUND The data control request specified by the @c reqId does not exist.
+ * @exception E_OBJECT_LOCKED The database instance associated with the specified @c pDbEnum is locked.
+ * @exception E_INVALID_FORMAT The database file associated with the specified @c pDbEnum is in an invalid format.
* @exception E_IO Either of the following conditions has occurred:
- * - An unexpected device failure has occurred as the media ejected suddenly.
- * - %File corruption is detected.
- * @exception E_MAX_EXCEEDED The size of sending buffer has exceeded the maximum limit.
+ * - An unexpected device failure has occurred as the media ejected suddenly.
+ * - %File corruption has been detected.
+ * @exception E_MAX_EXCEEDED The size of the sending buffer has exceeded the maximum limit.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @see Tizen::App::DataControlProviderManager::SendSqlDataControlInsertResult()
* @see Tizen::App::DataControlProviderManager::SendSqlDataControlUpdateDeleteResult()
* @see Tizen::App::DataControlProviderManager::SendDataControlError()
- * @see Tizen::App::ISqlDataControlProviderEventListener
*/
result SendSqlDataControlSelectResult(RequestId reqId, Tizen::Io::IDbEnumerator* pDbEnum);
/**
- * Sends the success result of INSERT request and the last inserted row ID to the application requesting
- * the SQL-type data control. @n
+ * Sends the success result of the INSERT request and the last inserted row ID to the application requesting for
+ * the SQL-friendly interface based data control. @n
* The data control provider must call the %SendSqlDataControlInsertResult() method to notify success to the requesting application.
* The application requesting the data control can get the success result and the last inserted row ID
* by implementing Tizen::App::ISqlDataControlResponseListener.
*
* @return An error code
* @param[in] reqId The request ID
- * @param[in] insertRowId The row ID of database changed by INSERT request
+ * @param[in] insertRowId The row ID of the database changed by the INSERT request
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG This method cannot send result for the specified @c reqId of SELECT, UPDATE, or DELETE request.
- * @exception E_OBJ_NOT_FOUND The data control request specified with the @c reqId did not exist.
+ * @exception E_INVALID_ARG The result for the specified @c reqId of the SELECT, UPDATE, or DELETE request cannot be sent.
+ * @exception E_OBJ_NOT_FOUND The data control request specified by the @c reqId does not exist.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @see Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
* @see Tizen::App::DataControlProviderManager::SendSqlDataControlUpdateDeleteResult()
* @see Tizen::App::DataControlProviderManager::SendDataControlError()
- * @see Tizen::App::ISqlDataControlProviderEventListener
* @see Tizen::Io::Database::GetLastInsertRowId()
*/
result SendSqlDataControlInsertResult(RequestId reqId, long long insertRowId);
/**
- * Sends the success result of UPDATE / DELETE request to the application requesting the SQL-type data control. @n
+ * Sends the success result of the UPDATE or DELETE request to the application requesting for the SQL-friendly interface based data control. @n
* The data control provider must call the %SendSqlDataControlUpdateDeleteResult() method to notify success to the requesting application.
* The application requesting the data control can get the success result by implementing Tizen::App::ISqlDataControlResponseListener.
*
* @return An error code
* @param[in] reqId The request ID
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG This method cannot send result for the specified @c reqId of SELECT or INSERT request.
- * @exception E_OBJ_NOT_FOUND The data control request specified with the @c reqId did not exist.
+ * @exception E_INVALID_ARG The result for the specified @c reqId of the SELECT or INSERT request cannot be sent.
+ * @exception E_OBJ_NOT_FOUND The data control request specified by the @c reqId does not exist.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @see Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
* @see Tizen::App::DataControlProviderManager::SendSqlDataControlInsertResult()
result SendSqlDataControlUpdateDeleteResult(RequestId reqId);
/**
- * Sends the success result and the result list of the provider to the application requesting the MAP-type
+ * Sends the success result and the result list of the provider to the application requesting for the key-value structured
* data control. @n
* The data control provider must call the %SendMapDataControlResult() method to notify success to the requesting application.
* The application requesting the data control can get the success result and the result set
* @param[in] reqId The request ID
* @param[in] pResultValueList The result list to request @n
* The type of objects contained in the specified @c pResultValueList must be
- * Tizen::Base::String class.
+ * Tizen::Base::String.
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG Either of the following conditions has occurred:
- * - The specified @c pResultValueList must be @c null if the request is one of
- * AddValue, SetValue, RemoveValue queries.
- * - The specified @c pResultValueList must not be @c null if the request is
- * GetValue() query.
- * @exception E_OBJ_NOT_FOUND The data control request specified with the @c reqId does not exist.
- * @exception E_MAX_EXCEEDED The size of sending buffer has exceeded the maximum limit.
+ * - The specified @c pResultValueList must be @c null if the request is an
+ * AddValue(), SetValue(), or RemoveValue() query.
+ * - The specified @c pResultValueList must not be @c null if the request is
+ * a GetValue() query.
+ * @exception E_OBJ_NOT_FOUND The data control request specified by the @c reqId does not exist.
+ * @exception E_MAX_EXCEEDED The size of the sending buffer has exceeded the maximum limit.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEEDED may be returned for messages over 16KB size.
* @see Tizen::App::DataControlProviderManager::SendDataControlError()
- * @see Tizen::App::IMapDataControlProviderEventListener
*/
result SendMapDataControlResult(RequestId reqId, Tizen::Base::Collection::IList* pResultValueList = null);
/**
- * Sends the provider error message to the application requesting the data control. @n
+ * Sends the provider error message to the application requesting for the data control. @n
* The data control provider must call the %SendDataControlError() method to notify failure to the requesting application.
* The application requesting the data control can get the failure result and the error message
* by implementing Tizen::App::ISqlDataControlResponseListener.
* @param[in] reqId The request ID
* @param[in] errorMsg The provider-defined error message
* @exception E_SUCCESS The method is successful.
- * @exception E_OBJ_NOT_FOUND The data control request specified with the @c reqId did not exist.
- * @exception E_MAX_EXCEEDED The size of sending buffer has exceeded the maximum limit.
+ * @exception E_OBJ_NOT_FOUND The data control request specified by the @c reqId does not exist.
+ * @exception E_MAX_EXCEEDED The size of the sending buffer has exceeded the maximum limit.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEEDED may be returned for messages over 16KB size.
+ * @remarks The recommended data size is under 16KB because a severe system performance degradation may occur for larger messages. @n
+ * @c E_MAX_EXCEEDED may be returned for messages over 16KB size.
* @see Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
* @see Tizen::App::DataControlProviderManager::SendSqlDataControlInsertResult()
* @see Tizen::App::DataControlProviderManager::SendSqlDataControlUpdateDeleteResult()
* @see Tizen::App::DataControlProviderManager::SendMapDataControlResult()
- * @see Tizen::App::ISqlDataControlProviderEventListener
* @see Tizen::App::IMapDataControlProviderEventListener
*/
result SendDataControlError(RequestId reqId, const Tizen::Base::String& errorMsg);
/**
- * Gets the data control provider manager instance.
+ * Gets a pointer to the %DataControlProviderManager instance.
*
* @since 2.0
*
- * @return A pointer to the %DataControlProviderManager instance if it succeeds, @n
- * else @c null
+ * @return A pointer to the %DataControlProviderManager instance, @n
+ * else @c null if it fails
*/
static DataControlProviderManager* GetInstance(void);