16.4.2 Action Execution API (Compatible with Old Versions)

This section explains the sound notification API (Mp_PlaySound).

Synopsis

long Mp_PlaySound (unsigned char *AppName,
                      int kind,
                      unsigned char *text_or_filename,
                      int repeat,
                      MpSoundParam *SoundParam)

Description

This emits the following sounds:

Message read out
WAV file playback
Beep

Parameters

AppName

Specify the address of the application that made the call. The application name must be 64 bytes or less in length.

kind

Specify the type of sound. Specify one of the following in this parameter.

SOUND_VOICE:: Reads out the message text.

SOUND_WAVE:: Plays a WAV file.

SOUND_BEEP:: Emits a beep.

text_or_filename

Specify one of the followings depending on the value of parameter kind.

When specifying SOUND_VOICE:: Specify the address of the message text that is to be read out.

When specifying SOUND_WAVE:: Specify the full path address of the file to be played to a value within the range specified in MAX_PATH.

When specifying SOUND_BEEP:: This parameter is invalid.

repeat

Specify the number of times the sound should be emitted. If 0 (zero) has been specified, the sound is repeated until stop processing has been completed.

SoundParam

Specify the address of the sound option information structure (MpSoundParam). If SOUND_VOICE has been specified, specify this when changing the system settings. This is invalid if SOUND_VOICE has not been specified. Specify NULL if this does not have to be set. If 0 (zero) is specified for all items, the system settings will be used.

Return Values

If the request is successfully accepted, an integer above 0 will be returned. Any value less than 0 is an error. The following table provides details about errors that may be returned.

Return Value	Meaning	Action
MPACT_PARAMERR	There is a parameter error.	Check for incorrect parameter settings.
MPACT_NOMEMORY	There is not enough memory.	Either increase the size of the page file or add more physical memory.
MPACT_NOTSOUND	The environment for playing sound has not been installed.	Check that a product equipped with a voice synthesizing engine compatible with Microsoft Speech API(SAPI)5.x has been installed.
MPACT_NOTMOVE	The Action Control Server has not been started.	Check that Systemwalker MpAosfB is running.
MPACT_COMFAIL	An error has occurred in communication with the Action Control Server.	Check that Systemwalker MpAosfB and Systemwalker MpAosfX are running.
MPACT_SYSERR	An error has occurred on the Action Control Server.	Refer to the message output to the event log or syslog, eliminate the cause of the error and then restart Systemwalker. If the problem persists after the cause of the error has been eliminated and Systemwalker has been restarted, use the maintenance information collection tool to collect event monitoring data and contact a Fujitsu SE.
MPACT_NOTDLL	DLL for the action request cannot be loaded.	Check that the file f3crhxac.dl (see Note), which is needed for action management, exists in the following folder: Systemwalker installation directory\mpwalker\bin If the file is not located in the above folder, either reinstall Systemwalker or use the maintenance information collection tool to collect event monitoring data and contact a Fujitsu SE.
MPACT_EXCEPT	The address of an invalid area has been specified.	An internal logic error has occurred. Collect data with the maintenance information collection tool and contact a Fujitsu SE.

Format of the Sound Option Information Structure (MpSoundParam)

typedef struct MpSoundParam_tag { 
    DWORD dwVoiceType ;
    DWORD dwIntonation ;
    DWORD dwPitch ;
    DWORD dwSpeed ;
    DWORD dwSpeedRate  ;
    DWORD dwTone ;
    DWORD dwVolume ;
} MpSoundParam ;

dwVoiceType

Specify the voice type.

VOICE_MALE:: This plays a male voice.

VOICE_FEMALE:: This plays a female voice.

dwIntonation

Specify an intonation level between 1 and 4.

dwPitch

Specify the pitch of the voice between 1 and 5.

dwSpeed

Specify the speed of the voice between 1 and 10.

dwSpeedRate

Specify the fluctuation of the speed of the voice between 1 and 10.

dwTone

Specify whether there is emphasis in high voice tone.

No:: 1

Yes:: 2

DWORD dwVolume

Specify the volume of the voice between 1 and 10.

Program Example

Below is an example program of the sound notification API:

#include "f3crhxac.h"

unsigned char *AppName = "Sound notification API" ;  // requested source application name
int kind               = SOUND_VOICE ;                     // read out text
unsigned char *text    = "an error has occurred. please contact your operator." ;
int repeat             = 0 ;                     // repeat until stop process is executed.
MpSoundParam  *SndPrm  = NULL ;                         // default value is used.
long           lrc ;

/* request for sound notification */
lrc = Mp_PlaySound(AppName,kind,text,repeat,NULL) ;
if ( lrc < 0 ) {
    /* error processing */
}

/* normal completion */

16.4.2.2 Pop-up Message Transmission (Specified Users) API

This section explains the pop-up message transmission (specified users) API (Mp_PopupUser).

Synopsis

long Mp_PopupUser (unsigned char *AppName,
           MpAddress *AddressList,
           int nAddressList, 
           unsigned char *MsgText)

Description

This API displays messages on specified computers or on computers to which specified users have logged on.

Parameters

AppName

Specify the address of the application that made the call. The application name must be 64 bytes or less in length.

AddressList

Specify the address of the destination information structure (MpAddress). Specify the name of the user or computer that is sending the pop-up message. If there are multiple names, specify them in an array. If NULL is specified, the pop-up message will be sent to all users logged on to the domain.

nAddressList

Specify the number of arrays specified in AddressList.

MsgText

Specify the address of the message that will appear in the pop-up window. The message has to be 128 bytes or less in length.

Return Values

If the request was successfully accepted, 0 or a higher integer will be returned. Any value less than 0 is an error. The following table provides details about errors that may be returned.

Return Value	Meaning	Action
MPACT_PARAMERR	There is a parameter error.	Check for incorrect parameter settings.
MPACT_NOMEMORY	There is not enough memory.	Either increase the size of the page file or add more physical memory.
MPACT_NOTADDRESS	There is no valid user name or computer name.	There is an error in the address specified in the address information structure (MpAddress). Correct the address specification.
MPACT_NOTMOVE	The Action Control Server has not been started.	Check that Systemwalker MpAosfB is running.
MPACT_COMFAIL	An error has occurred in communication with the Action Control Server. An error has occurred in communication with the Action Control Server.	Check that Systemwalker MpAosfB and Systemwalker MpAosfX are running.
MPACT_SYSERR	An error has occurred on the Action Control Server.	Refer to the message output to the event log or syslog, eliminate the cause of the error and then restart Systemwalker. If the problem persists after the cause of the error has been eliminated and Systemwalker has been restarted, use the maintenance information collection tool to collect event monitoring data and contact a Fujitsu SE.
MPACT_NOTDLL	DLL for the action request cannot be loaded.	Check that the file f3crhxac.dl (see Note), which is needed for action management, exists in the following folder: Systemwalker installation directory\mpwalker\bin If the file is not located in the above folder, either reinstall Systemwalker or use the maintenance information collection tool to collect event monitoring data and contact a Fujitsu SE.
MPACT_EXCEPT	The address of an invalid area has been specified.	An internal logic error has occurred. Collect data with the maintenance information collection tool and contact a Fujitsu SE.

Caution

Pop-up messages can only be used on Microsoft networks.

Format of the Destination Information Structure (MpAddress)

typedef struct MpAddress_tag {
    int type ;
    unsigned char *address ;
    char *addrid ;
} MpAddress ;

type

Specify the type of address that was specified in address.

TYPE_ADDRESS:: This is the user name or computer name.

TYPE_NAME:: This is the destination name.

address

Specify the user name/computer name or the address of the destination.

addrid

This parameter is enabled when Systemwalker Centric Manager is installed and "TYPE_NAME" is specified as the type parameter. Refer to the Systemwalker Centric Manager Reference Guide for details.

Program Example

Below is an example program of the pop-up message transmission (specified users) API:

#include "f3crhxac.h"

unsigned char *AppName = "pop-up API" ;    // requested source application name
MpAddress addr[2] ;                          // destination address storage area
int naddr ;
unsigned char *text    = "this will stop the system. " ;  // message text to be sent

long lrc ;

addr[0].type = TYPE_ADDRESS ;   // send a message  to users "operator" and "user01"
addr[0].address = "operator" ;                                     
addr[1].type = TYPE_ADDRESS ;
addr[1].address = "user01" ;
naddr = 2 ;

lrc = Mp_PopupUser(AppName,addr,naddr,text) ;
if ( lrc < 0 ) {
    /* error processing */
}

/* normal completion */

16.4.2.3 Pop-up Message Transmission (Domains) API

This section explains the pop-up message transmission (domain) API (Mp_PopupDomain).

Synopsis

long Mp_PopupDomain (unsigned char *AppName,
             char *domain,
             unsigned char *MsgText)

Description

This API displays pop-up messages on all computers that are connected to a specified domain.

Parameters

AppName

Specify the address of the application that made the call. The application name must be 64 bytes or less in length.

domain

Specify the address of the domain that will display the message. The domain name must be 15 bytes or less in length.

MsgText

Specify the address of the message that will appear in the pop-up window. The message has to be 128 bytes or less in length.

Return Values

If the request was successfully accepted, 0 or a higher integer will be returned. Any value less than 0 is an error. The following table provides details about errors that may be returned.

Return Value	Meaning	Action
MPACT_PARAMERR	There is a parameter error.	Check for incorrect parameter settings.
MPACT_NOMEMORY	There is not enough memory.	Either increase the size of the page file or add more physical memory.
MPACT_NOTMOVE	The Action Control Server has not been started.	Check that Systemwalker MpAosfB is running.
MPACT_COMFAIL	An error has occurred in communication with the Action Control Server.	Check that Systemwalker MpAosfB and Systemwalker MpAosfX are running.
MPACT_SYSERR	An error has occurred on the Action Control Server.	Refer to the message output to the event log or syslog, eliminate the cause of the error and then restart Systemwalker. If the problem persists after the cause of the error has been eliminated and Systemwalker has been restarted, use the maintenance information collection tool to collect event monitoring data and contact a Fujitsu SE.
MPACT_NOTDLL	DLL for the action request cannot be loaded.	Check that the file f3crhxac.dl (see Note), which is needed for action management, exists in the following folder: Systemwalker installation directory\mpwalker\bin If the file is not located in the above folder, either reinstall Systemwalker or use the maintenance information collection tool to collect event monitoring data and contact a Fujitsu SE.
MPACT_EXCEPT	The address of an invalid area has been specified.	An internal logic error has occurred. Collect data with the maintenance information collection tool and contact a Fujitsu SE.

Caution

Pop-up messages can only be used on Microsoft networks.

Program Example

Below is an example program of the pop-up message transmission (domains) API:

#include "f3crhxac.h"

unsigned char *AppName = "pop-up API" ;              // requested source application name
char *domain           = "Domain" ;                         // destination domain name
unsigned char *text    = "this will stop the system. " ; // message text to be sent
long lrc ;

lrc = Mp_PopupDomain(AppName,domain, text) ;
if ( lrc < 0 ) {
    /* error processing */
}

/* normal completion */

16.4.2.4 Pop-up Message Transmission (All Users) API

This section explains the pop-up message transmission (all users) API (Mp_PopupSession).

Synopsis

long Mp_PopupSession (unsigned char *AppName, 
                         unsigned char *MsgText)

Description

This API sends pop-up messages to all sessions connected to the server.

Parameters

AppName

Specify the address of the application that made the call. The application name must be 64 bytes or less in length.

MsgText

Specify the address of the message that will appear in the pop-up window. The message has to be 128 bytes or less in length.

Return Values

If the request was successfully accepted, 0 or a higher integer will be returned. Any value less than 0 is an error. The following table provides details about errors that may be returned.

Return Value	Meaning	Action
MPACT_PARAMERR	There is a parameter error.	Check for incorrect parameter settings.
MPACT_NOMEMORY	There is not enough memory.	Either increase the size of the page file or add more physical memory.
MPACT_NOTMOVE	The Action Control Server has not been started.	Check that Systemwalker MpAosfB is running.
MPACT_COMFAIL	An error has occurred in communication with the Action Control Server.	Check that Systemwalker MpAosfB and Systemwalker MpAosfX are running.
MPACT_SYSERR	An error has occurred on the Action Control Server.	Refer to the message output to the event log or syslog, eliminate the cause of the error and then restart Systemwalker. If the problem persists after the cause of the error has been eliminated and Systemwalker has been restarted, use the maintenance information collection tool to collect event monitoring data and contact a Fujitsu SE.
MPACT_NOTDLL	DLL for the action request cannot be loaded.	Check that the file f3crhxac.dl (see Note), which is needed for action management, exists in the following folder: Systemwalker installation directory\mpwalker\bin If the file is not located in the above folder, either reinstall Systemwalker or use the maintenance information collection tool to collect event monitoring data and contact a Fujitsu SE.
MPACT_EXCEPT	The address of an invalid area has been specified.	An internal logic error has occurred. Collect data with the maintenance information collection tool and contact a Fujitsu SE.

Caution

Pop-up messages can only be used on Microsoft networks.

Program Example

Below is an example program of the pop-up message transmission (all users) API:

#include "f3crhxac.h"

unsigned char *AppName = "pop-up API" ;            // requested source application name
unsigned char *text    = "this will stop the system. " ; //  message text to be sent
long lrc ;

lrc = Mp_PopupSession(AppName,text) ;
if ( lrc < 0 ) {
    /* error processing */
}

/* normal completion */