TutOptionSetVerifyFunc

Name

TutOptionSetVerifyFunc — create a function to verify that the option’s value is acceptable

Synopsis

T_BOOL TutOptionSetVerifyFunc(option, verify_func, arg) 
T_OPTION option; 
T_OPTION_VERIFY_FUNC verify_func; 
T_PTR arg; 

Arguments

option — option to register the verify function

verify_func — verify function

arg — function argument

Return Values

TRUE if operation was successful, FALSE otherwise.

Diagnostics

If TutOptionSetVerifyFunc fails, it returns FALSE and sets the global SmartSockets error number to:

Description

TutOptionSetVerifyFunc attaches a verify function verify_func to option. Before the value of option changes, verify_func is called. Write the code to validate the new value and return TRUE if it is valid, FALSE otherwise. The value of the option is changed only if TRUE is returned by verify_func. The function verify_func must have three arguments:

If the verify function returns FALSE, it issues diagnostic output with TutOut or TutWarning (before returning) to provide feedback to you; the other TutOption* functions do not issue any output in the case of the verify function returning FALSE.

Caution

The argument verify_func must return TRUE or FALSE. Other values are undefined.

When writing an option verify function, be sure to account for the possibility that new_value may be NULL. This happens when an option is set to UNKNOWN.

See Also

TutOptionCreate, TutOptionLookup

Examples

This example verifies that the option named num_opt is between 0.0 and 10.0:

/* This verify function is called when the */ 
/* value of option "num_opt" changes.     */ 
T_BOOL VerifyNum(T_OPTION option, 
                 T_PTR new_value, 
                 T_PTR arg) 
{ 
  T_REAL8 num_return; 
 
  num_return = *((T_REAL8 *)new_value); 
  if (num_return >= 0.0 && num_return <= 10.0) { 
    /* Value of "num_opt" will be changed to new_value */ 
    return TRUE; 
  } 
  else { 
    /* Value of "num_opt" will NOT be changed */ 
    TutOut("Illegal value %f for option %s.\n", 
         num_return, TutOptionGetName(option)); 
    return FALSE; 
  } 
} /* VerifyNum */ 
 
/* Below is a code fragment that could go into  */ 
/* an initialization routine.                                */ 
T_OPTION option; 
 
option = TutOptionCreate("num_opt", T_OPT_TYPE_NUMERIC); 
if (option == NULL) { 
  /* error */ 
} 
 
if (!TutOptionSetVerifyFunc(option, VerifyNum, NULL) ) { 
  /* error */ 
}