Smart Text Helper Library
[System]

Detailed Description

Smart Text Helper Library.

The smart text helper contains a function that can handle the back end of a smart text handler callback. See the ALP_MAX_SMART_TEXT documentation for more information about the smart text engine.


Functions

alp_status_t alp_smart_text_helper_create_request_for_mime_type (char *text, char *mimeType, GtkWidget *widget, char **verbsToRemove, int numVerbsToRemove, char **verbsToInclude, int numVerbsToInclude, AlpExg2Request *request)
 Create an exchange request in response to the user activating a smart text link.
alp_status_t alp_smart_text_helper_handle_mime_type (char *text, char *mimeType, GtkWidget *widget, char **verbsToRemove, int numVerbsToRemove, char **verbsToInclude, int numVerbsToInclude)
 Create and execute an exchange request to respond to the user activating a smart text link.

Function Documentation

alp_status_t alp_smart_text_helper_create_request_for_mime_type (  char *  text,
char *  mimeType,
GtkWidget *  widget,
char **  verbsToRemove,
int  numVerbsToRemove,
char **  verbsToInclude,
int  numVerbsToInclude,
AlpExg2Request *  request
) 
 

Create an exchange request in response to the user activating a smart text link.

Parameters:
[in] text string containing the phone number, URL, or email address
[in] mimeType string containing the Exchange Manager MIME type
[in] widget a widget that will be used to position the menu
[in] verbsToRemove an array of strings that specify verbs to be omitted from the menu
[in] numVerbsToRemove size of verbsToRemove array or -1 to remove all verbs
[in] verbsToInclude an array of strings that specify verbs to be included in the menu
[in] numVerbsToInclude size of verbsToInclude array
[out] request an AlpExgRequest that gets created
Returns:
ALP_STATUS_OK if all goes well

ALP_EXGMGR_ERR_API_ERR_ERROR if verbsToRemove is NULL and numVerbsToRemove is greater than 0

ALP_EXGMGR_ERR_API_ERR_ERROR if verbsToInclude is NULL and numVerbsToInclude is not zero

ALP_EXGMGR_ERR_USER_CANCEL_ERROR if the user exits from the menu

ALP_EXG_MGR_ERR_HANDLER_NOT_FOUND_ERROR if the final verb list is empty

Remarks:
This function creates an exchange request based on the specified mime type. It is very similar to the alp_smart_text_helper_handle_mime_type function except that it does not execute the exchange request after it creates it. Instead, it returns the request.
The actual verbs that appear in the menu are determined in the following way: the function retrieves the list of available verbs from the exchange manager. Then it removes all of the verbs in the verbsToRemove array or all available verbs if numVerbsToRemove is -1. It then adds all of the verbs in the verbsToInclude array. If the verbsToRemove array or the verbsToInclude array contains a verb that is not in the original list, the verb is silently ignored.

If the final list of verbs is empty, this function immediately returns ALP_EXG_MGR_ERR_HANDLER_NOT_FOUND_ERROR. If the final list of verbs has exactly one verb, this function creates an exchange request for the verb and returns it. If the final list of verbs has two or more verbs, this function displays a menu allowing the user choose a verb. Based on the choice, an Exchange Request is created and returned.

The default smart text tag handler calls this function with numVerbsToRemove set to 0 and numVerbsToInclude set to 0. In this case, the final list of verbs is exactly the same as the list that exchange manager returns for the mime type.

alp_status_t alp_smart_text_helper_handle_mime_type (  char *  text,
char *  mimeType,
GtkWidget *  widget,
char **  verbsToRemove,
int  numVerbsToRemove,
char **  verbsToInclude,
int  numVerbsToInclude
) 
 

Create and execute an exchange request to respond to the user activating a smart text link.

Parameters:
[in] text string containing the phone number, URL, or email address
[in] mimeType string containing the Exchange Manager MIME type
[in] widget a widget that will be used to position the menu
[in] verbsToRemove an array of strings that specify verbs to be omitted from the menu
[in] numVerbsToRemove size of verbsToRemove array or -1 to remove all verbs
[in] verbsToInclude an array of strings that specify verbs to be included in the menu
[in] numVerbsToInclude size of verbsToInclude array
Returns:
ALP_STATUS_OK if all goes well

ALP_EXGMGR_ERR_API_ERR_ERROR if verbsToRemove is NULL and numVerbsToRemove is greater than 0

ALP_EXGMGR_ERR_API_ERR_ERROR if verbsToInclude is NULL and numVerbsToInclude is not zero

ALP_EXGMGR_ERR_USER_CANCEL_ERROR if the user exits from the menu or cancels the request

Remarks:
This function does everything that happens after the user activates some smart text. First, it determines the exchange verbs that are available for the specified exchange manager mime type. If there are more than one verbs, it displays a popup menu with user-presentable versions of the verbs. When the user chooses one of the verbs, the function creates an exchange request and executes it.
The actual verbs that appear in the menu are determined in the following way: the function retrieves the list of available verbs from the exchange manager. Then it It removes all of the verbs in the verbsToRemove array or all available verbs if numVerbsToRemove is -1. It then adds all of the verbs in the verbsToInclude array. If the verbsToRemove array or the verbsToInclude array contains a verb that is not in the original list, the verb is silently ignored.

If the final list of verbs is empty, this function immediately returns ALP_EXG_MGR_ERR_HANDLER_NOT_FOUND_ERROR. If the final list of verbs has exactly one verb, this function creates an exchange request for the verb and executes it. If the final list of verbs has two or more verbs, this function displays a menu allowing the user choose a verb. Based on the choice, an exchange request is created and executed.

The default smart text tag handler calls this function with numVerbsToRemove set to 0 and numVerbsToInclude set to 0. In this case, the final list of verbs is exactly the same as the list that exchange manager returns for the mime type.

Generated on Wed Jul 30 07:06:42 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation

Copyright © 1999-2008 ACCESS CO., LTD. All rights reserved.