Subscription Manager

Detailed Description

ITK functions are provided for you to take advantage of the subscription for Assign Status and Attach event types. The following new ITK functions are implemented in the existing subscription_itk.cxx, tceventmgr_itk.cxx, and tcactionhandler.cxx in the \src\sub_mgr module.

Modules

Data Structures

struct TcSubscriptionActionMsg_s

Defines

#define SCM_class_name_c "ImanSubscription"

Typedefs

typedef struct
TcSubscriptionActionMsg_s TcSubscriptionActionMsg_t
typedef struct
TcSubscriptionActionMsg_s * TcSubscriptionActionMsg_p_t
typedef enum
SCM_subscribe_to_rev_option_e SCM_subscribe_to_rev_option_t
typedef enum
SCM_condition_math_operator_e SCM_condition_math_operator_t

Enumerations

enum SCM_subscribe_to_rev_option_e { SCM_subscribe_to_rev_none, SCM_subscribe_to_all_revs, SCM_subscribe_to_item_revs, SCM_subscribe_to_baseline_revs }
enum SCM_condition_math_operator_e { SCM_equal = POM_enquiry_equal, SCM_not_equal = POM_enquiry_not_equal }

Functions

SUB_MGR_API int SCM_build_subscription_msg (tag_t subscriber, tag_t targetObject, char *objStrOfTarget, tag_t targetObjectType, tag_t eventType, date_t eventTime, TcSubscriptionActionMsg_t *subscriptionMsg)
SUB_MGR_API int SCM_subscribe (tag_t target, tag_t subscriber, tag_t event_type, tag_t handler, date_t execution_time, date_t expiration_date, int parameter_count, const char **handler_parameters, tag_t *subscription)
SUB_MGR_API int SCM_subscribe_with_notification (tag_t target, tag_t subscriber, tag_t event_type, tag_t handler, date_t execution_time, date_t expiration_date, int parameter_count, const char **handler_parameters, tag_t notification, tag_t *subscription)
SUB_MGR_API int SCM_subscribe_with_notification_options (tag_t target, tag_t subscriber, tag_t event_type, tag_t handler, date_t execution_time, date_t expiration_date, int parameter_count, const char **handler_parameters, const char *subject, const char *message, int properties_count, const char **properties, tag_t *subscription)
SUB_MGR_API int SCM_ask_notification (tag_t subscription, tag_t *notification)
SUB_MGR_API int SCM_set_notification (tag_t subscription, tag_t notification)
SUB_MGR_API int SCM_unsubscribe (tag_t subscription)
SUB_MGR_API int SCM_find_subscription (tag_t target, tag_t subscriber, tag_t event_type, tag_t handler, tag_t *subscription)
SUB_MGR_API int SCM_set_target (tag_t subscription, tag_t target)
SUB_MGR_API int SCM_set_subscriber (tag_t subscription, tag_t subscriber)
SUB_MGR_API int SCM_set_event_type (tag_t subscription, tag_t event_type)
SUB_MGR_API int SCM_set_handler (tag_t subscriptioni, tag_t handler)
SUB_MGR_API int SCM_set_execution_time (tag_t subscription, date_t execution_time)
SUB_MGR_API int SCM_set_expiration_date (tag_t subscription, date_t expiration_date)
SUB_MGR_API int SCM_set_handler_parameters (tag_t subscription, int count, char **parameters)
SUB_MGR_API int SCM_ask_target (tag_t subscription, tag_t *target)
SUB_MGR_API int SCM_ask_subscriber (tag_t subscription, tag_t *subscriber)
SUB_MGR_API int SCM_ask_event_type (tag_t subscription, tag_t *event_type)
SUB_MGR_API int SCM_ask_handler (tag_t subscription, tag_t *handler)
SUB_MGR_API int SCM_ask_execution_time (tag_t subscription, date_t *execution_time)
SUB_MGR_API int SCM_ask_expiration_date (tag_t subscription, date_t *expiration_date)
SUB_MGR_API int SCM_ask_handler_parameters (tag_t subscription, int *count, char ***parameters)
SUB_MGR_API int SCM_ask_notification_subject (tag_t subscription, char **subject)
SUB_MGR_API int SCM_set_notification_subject (tag_t subscription, char *subject)
SUB_MGR_API int SCM_ask_notification_message (tag_t subscription, char **message)
SUB_MGR_API int SCM_set_notification_message (tag_t subscription, char *message)
SUB_MGR_API int SCM_ask_notification_properties (tag_t subscription, int *count, char ***properties)
SUB_MGR_API int SCM_set_notification_properties (tag_t subscription, int count, char **properties)
SUB_MGR_API int SCM_subscribe_assign_status_event (tag_t target, tag_t subscriber, tag_t handler, date_t execution_time, date_t expiration_date, int parameter_count, const char **parameters, const char *release_status_type_name, logical all_rev_flag, tag_t *subscription)
SUB_MGR_API int SCM_subscribe_attach_event (tag_t target, tag_t subscriber, tag_t handler, date_t execution_time, date_t expiration_date, int parameter_count, const char **parameters, const char *relation_type_name, const char *secondary_object_type_name, logical all_rev_flag, tag_t *subscription)
SUB_MGR_API int SCM_subscribe_to_status_event (tag_t target, tag_t subscriber, tag_t handler, date_t execution_time, date_t expiration_date, int parameter_count, const char **parameters, SCM_condition_math_operator_t math_operator, const char *release_status_type_name, SCM_subscribe_to_rev_option_t rev_option, tag_t *subscription)
SUB_MGR_API int SCM_subscribe_to_rev_create_event (tag_t target, tag_t subscriber, tag_t handler, date_t execution_time, date_t expiration_date, int parameter_count, const char **parameters, SCM_subscribe_to_rev_option_t rev_option, tag_t *subscription)
SUB_MGR_API void write_Attributexml_keyword (const char *prefix, const char *keyword1, const char *value1, const char *keyword2, const char *value2, char **buffer)
SUB_MGR_API int SCM_get_subscrible_types (const char *childTypeOption, int *count, tag_t **typesTags)

Define Documentation

#define SCM_class_name_c "ImanSubscription"

Definition at line 32 of file subscription.h.

Typedef Documentation

typedef enum SCM_condition_math_operator_e SCM_condition_math_operator_t

typedef enum SCM_subscribe_to_rev_option_e SCM_subscribe_to_rev_option_t

typedef struct TcSubscriptionActionMsg_s * TcSubscriptionActionMsg_p_t

typedef struct TcSubscriptionActionMsg_s TcSubscriptionActionMsg_t

Enumeration Type Documentation

enum SCM_condition_math_operator_e

Enumerator:

SCM_equal
SCM_not_equal

Definition at line 64 of file subscription.h.

enum SCM_subscribe_to_rev_option_e

Enumerator:

SCM_subscribe_to_rev_none
SCM_subscribe_to_all_revs
SCM_subscribe_to_item_revs
SCM_subscribe_to_baseline_revs

Definition at line 56 of file subscription.h.

Function Documentation

SUB_MGR_API int SCM_ask_event_type	(	tag_t	subscription,
		tag_t *	event_type
	)

Parameters:

subscription	(I)
event_type	(O)

SUB_MGR_API int SCM_ask_execution_time	(	tag_t	subscription,
		date_t *	execution_time
	)

Parameters:

subscription	(I)
execution_time	(O)

SUB_MGR_API int SCM_ask_expiration_date	(	tag_t	subscription,
		date_t *	expiration_date
	)

Parameters:

subscription	(I)
expiration_date	(O)

SUB_MGR_API int SCM_ask_handler	(	tag_t	subscription,
		tag_t *	handler
	)

Parameters:

subscription	(I)
handler	(O)

SUB_MGR_API int SCM_ask_handler_parameters	(	tag_t	subscription,
		int *	count,
		char ***	parameters
	)

Parameters:

subscription	(I)
count	(O)
parameters	(OF) count

SUB_MGR_API int SCM_ask_notification	(	tag_t	subscription,
		tag_t *	notification
	)

SUB_MGR_API int SCM_ask_notification_message	(	tag_t	subscription,
		char **	message
	)

Retrieves the e-mail message to be displayed in notifications for the given subscription.

This function returns:

ITK_ok on success
POM_invalid_tag on incorrect subscription object tag

Parameters:

subscription	(I) Subscription object
message	(OF) Message body of the notification e-mail

SUB_MGR_API int SCM_ask_notification_properties	(	tag_t	subscription,
		int *	count,
		char ***	properties
	)

Retrieves the object properties to be displayed in notifications for the given subscription.

The returned array of properties should be freed with a single MEM_free call.

This function returns:

ITK_ok on success
POM_invalid_tag on incorrect subscription object tag

Parameters:

subscription	(I) Subscription object
count	(O) Number of properties
properties	(OF) count Object properties to be displayed in the body of the notification e-mail

SUB_MGR_API int SCM_ask_notification_subject	(	tag_t	subscription,
		char **	subject
	)

Retrieves the e-mail subject to be displayed in notifications for the given subscription.

This function returns:

ITK_ok on success
POM_invalid_tag on incorrect subscription object tag

Parameters:

subscription	(I) Subscription object
subject	(OF) Subject of the notification e-mail

SUB_MGR_API int SCM_ask_subscriber	(	tag_t	subscription,
		tag_t *	subscriber
	)

Parameters:

subscription	(I)
subscriber	(O)

SUB_MGR_API int SCM_ask_target	(	tag_t	subscription,
		tag_t *	target
	)

Parameters:

subscription	(I)
target	(O)

SUB_MGR_API int SCM_build_subscription_msg	(	tag_t	subscriber,
		tag_t	targetObject,
		char *	objStrOfTarget,
		tag_t	targetObjectType,
		tag_t	eventType,
		date_t	eventTime,
		TcSubscriptionActionMsg_t *	subscriptionMsg
	)

Parameters:

subscriber	(I)
targetObject	(I)
objStrOfTarget	(I)
targetObjectType	(I)
eventType	(I)
eventTime	(I)
subscriptionMsg	(O)

SUB_MGR_API int SCM_find_subscription	(	tag_t	target,
		tag_t	subscriber,
		tag_t	event_type,
		tag_t	handler,
		tag_t *	subscription
	)

Parameters:

target	(I)
subscriber	(I)
event_type	(I)
handler	(I)
subscription	(O)

SUB_MGR_API int SCM_get_subscrible_types	(	const char *	childTypeOption,
		int *	count,
		tag_t **	typesTags
	)

SUB_MGR_API int SCM_set_event_type	(	tag_t	subscription,
		tag_t	event_type
	)

Parameters:

subscription	(I)
event_type	(I)

SUB_MGR_API int SCM_set_execution_time	(	tag_t	subscription,
		date_t	execution_time
	)

Parameters:

subscription	(I)
execution_time	(I)

SUB_MGR_API int SCM_set_expiration_date	(	tag_t	subscription,
		date_t	expiration_date
	)

Parameters:

subscription	(I)
expiration_date	(I)

SUB_MGR_API int SCM_set_handler	(	tag_t	subscriptioni,
		tag_t	handler
	)

Parameters:

subscriptioni	(I)
handler	(I)

SUB_MGR_API int SCM_set_handler_parameters	(	tag_t	subscription,
		int	count,
		char **	parameters
	)

Parameters:

subscription	(I)
count	(I)
parameters	(I) count

SUB_MGR_API int SCM_set_notification	(	tag_t	subscription,
		tag_t	notification
	)

SUB_MGR_API int SCM_set_notification_message	(	tag_t	subscription,
		char *	message
	)

Sets the e-mail message to be displayed in notifications for the given subscription.

This function returns:

ITK_ok on success
POM_invalid_tag on incorrect subscription object tag
SCM_no_modify_access modify access is not permitted for this subscription
POM_string_too_long for input subject string too long

Parameters:

subscription	(I) Subscription object
message	(I) Message body of the notification e-mail

SUB_MGR_API int SCM_set_notification_properties	(	tag_t	subscription,
		int	count,
		char **	properties
	)

Sets the object properties to be displayed in notifications for the given subscription.

This function returns:

ITK_ok on success
POM_invalid_tag on incorrect subscription object tag
SCM_no_modify_access modify access is not permitted for this subscription
PROP_not_found invalid property name for the subscription target object

Parameters:

subscription	(I) Subscription object
count	(I) Number of properties. Can be zero.
properties	(I) Object properties to be displayed in the body of the notification e-mail

SUB_MGR_API int SCM_set_notification_subject	(	tag_t	subscription,
		char *	subject
	)

Sets the e-mail subject to be displayed in notifications for the given subscription.

This function returns:

ITK_ok on success
POM_invalid_tag on incorrect subscription object tag
SCM_no_modify_access modify access is not permitted for this subscription
POM_string_too_long for input subject string too long

Parameters:

subscription	(I) Subscription object
subject	(I) Subject of the notification e-mail

SUB_MGR_API int SCM_set_subscriber	(	tag_t	subscription,
		tag_t	subscriber
	)

Parameters:

subscription	(I)
subscriber	(I)

SUB_MGR_API int SCM_set_target	(	tag_t	subscription,
		tag_t	target
	)

Parameters:

subscription	(I)
target	(I)

SUB_MGR_API int SCM_subscribe	(	tag_t	target,
		tag_t	subscriber,
		tag_t	event_type,
		tag_t	handler,
		date_t	execution_time,
		date_t	expiration_date,
		int	parameter_count,
		const char **	handler_parameters,
		tag_t *	subscription
	)

Creates a new subscription object against the target object.

Subscriptions created from this ITK do not function as notification subscriptions. This API is intended for triggering custom handlers or handlers that do not specifically notify the user. In order to create Notification subscriptions, use SCM_subscribe_with_notification_options and the STDHANDLER_MAIL_NOTIFY_ID handler.

Use TCACTIONHANDLER_find_handler to retrieve the handler tag.

Retrieve the event tag with TCEVENTTYPE_find.

This function returns:

ITK_ok on success
SCM_invalid_subscriber no subscriber tag was specified

Parameters:

target	(I) The object to monitor for the specified event type
subscriber	(I) User that is subscribing to the change
event_type	(I) Type of event that will trigger the subscription
handler	(I) Handler that will process the subscription
execution_time	(I) When the subscription should be processed. NULLDATE will trigger immediate processing.
expiration_date	(I) When the subscription expires. NULLDATE specifies no expiration.
parameter_count	(I) Number of parameters being passed to the handler
handler_parameters	(I) Parameters being passed to the handler
subscription	(O) New subscription object

SUB_MGR_API int SCM_subscribe_assign_status_event	(	tag_t	target,
		tag_t	subscriber,
		tag_t	handler,
		date_t	execution_time,
		date_t	expiration_date,
		int	parameter_count,
		const char **	parameters,
		const char *	release_status_type_name,
		logical	all_rev_flag,
		tag_t *	subscription
	)

This function is used for creating a subscription for Assign Status event type.

Restrictions:

This ITK function is used only for Assign Status event type.

Parameters:

target	(I) Tag of the target object
subscriber	(I) User tag for the subscriber
handler	(I) Tag of the action handler
execution_time	(I) Time when the event needs to be processed by the daemon
expiration_date	(I) Date when the subscription expires
parameter_count	(I) Number of action handler parameters
parameters	(I) parameter_count String array of action handler parameters
release_status_type_name	(I) This is the name of a release status type. If the string is an empty string, it means any status.
all_rev_flag	(I) If this flag is true, the target object subscribed must be an Item object so that when release status is assigned to an ItemRevision object under the Item object, proper action gets carried out. If this flag is false, then proper action gets carried out when the target object itself is assigned a release status.
subscription	(O) The tag of created subscription

SUB_MGR_API int SCM_subscribe_attach_event	(	tag_t	target,
		tag_t	subscriber,
		tag_t	handler,
		date_t	execution_time,
		date_t	expiration_date,
		int	parameter_count,
		const char **	parameters,
		const char *	relation_type_name,
		const char *	secondary_object_type_name,
		logical	all_rev_flag,
		tag_t *	subscription
	)

This function is used for creating a subscription for Attach event type.

Restrictions:

This ITK function is used only for Attach event type.

Parameters:

target	(I) Tag of the target object
subscriber	(I) User tag for the subscriber
handler	(I) Tag of the action handler
execution_time	(I) Time when the event is processed by the daemon
expiration_date	(I) Date when the subscription expires
parameter_count	(I) Number of action handler parameters
parameters	(I) parameter_count String array of action handler parameters
relation_type_name	(I) This is the name of a Teamcenter Engineering relation. If the string is an empty string, it means any relation.
secondary_object_type_name	(I) This is the name of a secondary object type. If the string is an empty string, it means any object type.
all_rev_flag	(I) If this flag is true, the target object subscribed must be an Item object so that when a secondary object is attached to an ItemRevision object under the Item object, proper action gets carried out. If this flag is false, then proper action gets carried out when the target object itself gets a secondary object attached.
subscription	(O) The tag of created subscription

SUB_MGR_API int SCM_subscribe_to_rev_create_event	(	tag_t	target,
		tag_t	subscriber,
		tag_t	handler,
		date_t	execution_time,
		date_t	expiration_date,
		int	parameter_count,
		const char **	parameters,
		SCM_subscribe_to_rev_option_t	rev_option,
		tag_t *	subscription
	)

This function is used for creating a subscription for New IR event type.

Restrictions:

This ITK function is used only for New IR event type.

Parameters:

target	(I) Tag of the target object that must be an item
subscriber	(I) User tag for the subscriber
handler	(I) Tag of the action handler
execution_time	(I) Time when the event needs to be processed by the daemon
expiration_date	(I) Date when the subscription expires
parameter_count	(I) Number of action handler parameters
parameters	(I) parameter_count String array of action handler parameters
rev_option	(I) if SCM_subscribe_to_all_revs, a new IR event is fired when any item revision is created for the target item. if SCM_subscribe_to_item_revs, a new IR event is fired when any Base item revision is created for the target item. if SCM_subscribe_to_baseline_revs, a new IR event is fired when any Baseline item revision is created for the target item. SCM_subscribe_to_rev_none option is NOT applicable and the target must be an item
subscription	(O) The tag of created subscription

SUB_MGR_API int SCM_subscribe_to_status_event	(	tag_t	target,
		tag_t	subscriber,
		tag_t	handler,
		date_t	execution_time,
		date_t	expiration_date,
		int	parameter_count,
		const char **	parameters,
		SCM_condition_math_operator_t	math_operator,
		const char *	release_status_type_name,
		SCM_subscribe_to_rev_option_t	rev_option,
		tag_t *	subscription
	)

This function is used for creating a subscription for Assign Status event type.

Restrictions:

This ITK function is used only for Assign Status event type.

Parameters:

target	(I) Tag of the target object
subscriber	(I) User tag for the subscriber
handler	(I) Tag of the action handler
execution_time	(I) Time when the event needs to be processed by the daemon
expiration_date	(I) Date when the subscription expires
parameter_count	(I) Number of action handler parameters
parameters	(I) parameter_count String array of action handler parameters
math_operator	(I) math operator for subscription condition, if SCM_equal, event fired for the target has the given status assigned if SCM_not_equal, event fired if the target has an assigned status different from the given status. SCM_not_equal math operator is NOT appliable if release status type name input is empty
release_status_type_name	(I) This is the name of a release status type. If the string is an empty string, it means any status.
rev_option	(I)if SCM_subscribe_to_rev_none, no event is fired when a status event occurs on any item revision of the target item, but the event is fired only when a status event occurs on the target item. if SCM_subscribe_to_all_revs, a status event is also fired when a status event occurs on any item revision of the target item. if SCM_subscribe_to_item_revs, a status event is also fired when a status event occurs on any Base item revision of the target item. if SCM_subscribe_to_baseline_revs, a status event is also fired when a status event occurs on any Baseline item revision of the target item. this option is applicable only if the target is an item
subscription	(O) The tag of created subscription

SUB_MGR_API int SCM_subscribe_with_notification	(	tag_t	target,
		tag_t	subscriber,
		tag_t	event_type,
		tag_t	handler,
		date_t	execution_time,
		date_t	expiration_date,
		int	parameter_count,
		const char **	handler_parameters,
		tag_t	notification,
		tag_t *	subscription
	)

Parameters:

target	(I)
subscriber	(I)
event_type	(I)
handler	(I)
execution_time	(I)
expiration_date	(I)
parameter_count	(I)
handler_parameters	(I) parameter_count
notification	(I)
subscription	(O)

SUB_MGR_API int SCM_subscribe_with_notification_options	(	tag_t	target,
		tag_t	subscriber,
		tag_t	event_type,
		tag_t	handler,
		date_t	execution_time,
		date_t	expiration_date,
		int	parameter_count,
		const char **	handler_parameters,
		const char *	subject,
		const char *	message,
		int	properties_count,
		const char **	properties,
		tag_t *	subscription
	)

Creates a new object subscription against the target object.

This API allows the parameters of the notification e-mail to be specified.

Use TCACTIONHANDLER_find_handler to retrieve the handler tag. For e-mail notification, use the STDHANDLER_MAIL_NOTIFY_ID handler. The handler parameters are the IDs of the users to be notified.

Retrieve the event tag with TCEVENTTYPE_find.

This function returns:

ITK_ok on success
SCM_invalid_subscriber no subscriber tag was specified
POM_string_too_long for input subject string too long
PROP_not_found invalid property name for the subscription target object

Parameters:

target	(I) The object to monitor for the specified event type
subscriber	(I) User that is subscribing to the change
event_type	(I) Type of event that will trigger the subscription
handler	(I) Handler that will process the notification
execution_time	(I) When the subscription should be processed. NULLDATE will trigger immediate processing.
expiration_date	(I) When the subscription expires. NULLDATE specifies no expiration.
parameter_count	(I) Number of parameters being passed to the handler
handler_parameters	(I) Parameters being passed to the handler. For the STDHANDLER_MAIL_NOTIFY_ID handler, the user IDs of the people to be notified.
subject	(I) Subject of the notification e-mail
message	(I) Message body of the notification e-mail
properties_count	(I) Number of properties to include in the notification e-mail
properties	(I) Properties to include in the notification e-mail
subscription	(O) New subscription object

SUB_MGR_API int SCM_unsubscribe ( tag_t subscription )

Parameters:

subscription

(I)

SUB_MGR_API void write_Attributexml_keyword	(	const char *	prefix,
		const char *	keyword1,
		const char *	value1,
		const char *	keyword2,
		const char *	value2,
		char **	buffer
	)