mh5program.c

Go to the documentation of this file.

/*******************************************************************************
 * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
 * Copyright © 2004 Ocean Blue Software Ltd
 * Copyright © 2000 Koninklijke Philips Electronics N.V
 *
 * This file is part of a DTVKit Software Component
 * You are permitted to copy, modify or distribute this file subject to the terms
 * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
 * 
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
 * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 * 
 * If you or your organisation is not a member of DTVKit then you have access
 * to this source code outside of the terms of the licence agreement
 * and you are expected to delete this and any associated files immediately.
 * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
 *******************************************************************************/
/*---includes for this file--------------------------------------------------*/
#include "mh5program.h"
#include "mh5object.h"          /* for actions                  */
#include "mh5variable.h"        /* for actions                  */
#include "mh5queue.h"           /* Events           */
#include "mh5final.h"           /* for subclasses               */
#include "mh5prgs.h"            /* API to program execution     */
#include "mh5memory.h"          /* constructor/destructor       */
#include "mh5debug.h"

#ifdef MH5PRINTOUT
#include <string.h>
#endif

/*---constant definitions for this file--------------------------------------*/


/*---local typedef structs for this file-------------------------------------*/

/*---local (static) variable declarations for this file----------------------*/

/*---local function definitions----------------------------------------------*/

/*---global function definitions---------------------------------------------*/

/*
   Debug
 */
#ifdef MH5PRINTOUT

void MHEG5programPrint(MHEG5Program *program, char *out)
{
   MHEG5ingredientPrint(&program->ingredient, out);
   MHEG5indent(out);
   MHEG_PRINT(out, ":Name ");
   MHEG5stringPrint(program->name, out);
   MHEG5newLine(out);

   if (!program->initiallyAvailable)
   {
      MHEG5indent(out);
      MHEG_PRINT(out, ":InitiallyAvailable FALSE");
      MHEG5newLine(out);
   }
   if (program->programConnectionTag != 0)
   {
      MHEG5indent(out);
      MHEG_PRINT(out, ":ConnectionTag ");
      MHEG5intPrint(program->programConnectionTag, out);
      MHEG5newLine(out);
   }
}

#endif


/*
 */

/*
     Constructor
 */
static void MHEG5programInit(MHEG5Program *program)
{
   assert(program);

   MHEG5ingredientInit(&program->ingredient);

   program->initiallyAvailable = MHEG5TRUE;
}

void MHEG5programFree(MHEG5Program *program)
{
   assert(program);

   MHEG5ingredientFree(&program->ingredient);

   MHEG5stringDestruct(&program->name);
}

/*
     Constructors for Subclasses (as they have no additional functionality
 */
void MHEG5residentProgramInit(MHEG5Program *program)
{
   assert(program);

   MHEG5programInit(program);
}

void MHEG5residentProgramFree(MHEG5Program *program)
{
   assert(program);

   MHEG5programFree(program);
}

void MHEG5remoteProgramInit(MHEG5Program *program)
{
   assert(program);

   MHEG5programInit(program);
}

void MHEG5remoteProgramFree(MHEG5Program *program)
{
   assert(program);

   MHEG5programFree(program);
}

void MHEG5interchangedProgramInit(MHEG5Program *program)
{
   assert(program);

   MHEG5programInit(program);
}

void MHEG5interchangedProgramFree(MHEG5Program *program)
{
   assert(program);

   MHEG5programFree(program);
}

/*
     Internal behaviours
 */
void MHEG5programPrepare(MHEG5Program *program)
{
   assert(program);

   MHEG5ProgramSetStartFunc(program);

   MHEG5ingredientPrepare(&program->ingredient);
}

/*
     Activation
     1. If not done during preparation, locate the external procedural code by using
     the Name attribute.
     2. If the external procedural code is not found, disregard this action. Otherwise,
     3. Set the parameters of the external procedural code of the Program as
     indicated by Parameters.
     4. Apply the Activation behaviour as inherited from the base class.
     5. Start execution of the external procedural code synchronously or
     asynchronously according to the action invoking the execution..
     6. Set the RunningStatus attribute to True.
     7. Generate an IsRunning event.
 */
MHEG5ErrorCode MHEG5programActivate(MHEG5Program *program)
{
   MHEG5ErrorCode rc;
   MHEG5Root *callVar;

   assert(program);

   /* 1. If not done during preparation, locate the external procedural code by using
    *    the Name attribute.
    * 2. If the external procedural code is not found, disregard this action.
    */
   MHEG5resolveORef(program->parameter, &callVar);
   if (!callVar || callVar->clazz != MHEG5BOOLEANVARIABLE)
   {
      rc = MHEG5ERR_WRONGPARAM;
   }
   else if (program->startFunc == NULL)
   {
      ((MHEG5BooleanVariable *) callVar)->value = MHEG5FALSE;
     #ifdef TRACING
      extra_trace_param = (int)program->name.data;
     #endif
      rc = MHEG5ERR_NOTSUPPORTEDBYPROFILE;
   }
   else
   {
      /* The following step is performed as part of the program implementation:
       *
       * 3. Set the parameters of the external procedural code of the Program as
       *    indicated by Parameters.
       */
      if (!program->ingredient.root.runningStatus)
      {
         /* 4. Apply the Activation behaviour as inherited from the base class. */
         if (!program->ingredient.root.availabilityStatus)
         {
            MHEG5ingredientPrepare(&program->ingredient); /*program prepare*/
         }
         /* MHEG5ingredientActivate(&program->ingredient); <- this does nothing */

         /* 5. Start execution of the external procedural code synchronously or
          *    asynchronously according to the action invoking the execution.
          */

         /* Set the forkSucceededValue to be NULL. This will be set to a pointer to
          * an MHEG5Bool if the program implements the fork action (program has not
          * finished when the program implementation function returns). For all
          * others it remains NULL and the program will have finished when the
          * program implementation function ends.
          */
         program->forkSucceededValue = NULL;

         ((MHEG5BooleanVariable *) callVar)->value = MHEG5FALSE;
         rc = (program->startFunc)(program);

         /* 6. Set the RunningStatus attribute to True. */
         program->ingredient.root.runningStatus = MHEG5TRUE;

         /* 7. Generate an IsRunning event. */
         MHEG5sendSync((MHEG5Root *) program, MHEG5ISRUNNING, 0);
      }
      else
      {
         rc = MHEG5ERR_TARGETNOTACTIVE;
      }
   }
   return rc;
}

/*
     Deactivation
     If the RunningStatus attribute is False, ignore this action. Otherwise, execute the
     following sequence of actions:
     1. Force the end of execution of the Program.
     2. Apply Deactivation behaviour as inherited from the base class.
     NOTE - The Deactivation behaviour generates an IsStopped event, as defined in
     Root.
 */
void MHEG5programDeactivate(MHEG5Program *program)
{
   assert(program);
   if (program->stopFunc != NULL)
   {
      (program->stopFunc)(program);
   }
   if (program->ingredient.root.runningStatus)
   {
      MHEG5ingredientDeactivate(&program->ingredient);
   }
}

void MHEG5programDestruct(MHEG5Program *program)
{
   assert(program);
   if (program->stopFunc != NULL)
   {
      (program->stopFunc)(program);
   }
   MHEG5ingredientDestruct(&program->ingredient);
}

/*
     Actions
 */
/*
     Call (CallSucceeded, Parameters)
     Request execution of an external piece of procedural code and wait for the end of
     execution.
     Execute the following sequence of actions:
     1. If the Program is non-available, apply the Preparation behaviour.
     2. If the Program is active, disregard this action. Otherwise,
     3. Apply the Activation behaviour.
     4. Wait for the execution of the external procedural code to finish. If the
        Program finishes abnormally, set the Variable referenced by CallSucceeded
        to False; otherwise, set it to True.
     5. Set the value of the Variables referenced by Parameters to the values
        returned by the Program (these may be invalid if CallSucceeded is False).
     6. Apply the Deactivation behaviour.

     Provisions of use:
     CallSucceeded shall be set to an active BooleanVariable object.
     Parameters shall be set to a list of values corresponding to the expected
     parameters of the external procedural code. The order of the Parameters list
     shall correspond to the order of parameters of the procedural code. Parameters
     passed by value shall be set directly to the corresponding value. Parameters
     passed by reference shall be passed via active Variable objects of the
     corresponding data type.
 */
MHEG5ErrorCode MHEG5call(MHEG5Root *target, MHEG5GList *params)
{
   MHEG5ErrorCode rc;

   if (!params)
   {
      rc = MHEG5ERR_WRONGNUMBEROFPARAMS;
   }
   else
   {
      /* Check that target class is a subclass of Program */
      switch (target->clazz)
      {
         default:
            /* Target class is not a subclass of Program */
            rc = MHEG5ERR_WRONGTARGET;
            break;

         case MHEG5REMOTEPROGRAM:
         case MHEG5INTERCHANGEDPROGRAM:
            /* Target class is not a supported by UK Profile - or any other ..yet */
            rc = MHEG5ERR_NOTSUPPORTEDBYPROFILE;
            break;

         case MHEG5RESIDENTPROGRAM:
            /* 1. If the Program is non-available, apply the Preparation behaviour. */
            if (!target->availabilityStatus)
            {
               MHEG5programPrepare((MHEG5Program *)target);
            }
            /* 2. If the Program is active, disregard this action. */
            if (target->runningStatus)
            {
               rc = MHEG5ERR_NOERROR;
            }
            else
            {
               /* 3. Apply the Activation behaviour. */
               ((MHEG5Program *) target)->parameter = params;

               /* The program is Called, not Forked */
               ((MHEG5Program *) target)->forked = MHEG5FALSE;

               rc = MHEG5programActivate((MHEG5Program *)target);

               /* The following steps are performed by the program implementation:
                *
                * 4. Wait for the execution of the external procedural code to finish. If the
                *    Program finishes abnormally, set the Variable referenced by CallSucceeded
                *    to False; otherwise, set it to True.
                * 5. Set the value of the Variables referenced by Parameters to the values
                *    returned by the Program (these may be invalid if CallSucceeded is False).
                */
               /* 6. Apply the Deactivation behaviour - in ProgramCompleted() */
               MHEG5ingredientDeactivate((MHEG5Ingredient *)target);
            }
            break;
      }
   }

   return rc;
}

/*
     Fork (ForkSucceeded, Parameters)
     Request execution of an external piece of procedural code without waiting for the
     end of execution.
     Execute the following sequence of actions:
     1. If the Program is non-available, apply the Preparation behaviour.
     2. If the Program is active, disregard this action. Otherwise,
     3. Apply the Activation behaviour.
     4. Pass control back to the MHEG-5 engine without waiting for the execution
        of the external procedural code to finish.
        When the execution of the external procedural code finishes, execute the following
        sequence of actions:
     1. If the Program finishes abnormally, set the Variable referenced by
        ForkSucceeded to False; otherwise, set it to True.
     2. Set the value of the Variables referenced by Parameters to the values
        returned by the Program (these may be invalid if ForkSucceeded is
        False).
     3. Apply the Deactivation behaviour.
     4. Generate an AsynchStopped event.
     NOTE - Parameters may be modified by the Program, in that case, these
     parameters are not defined until the Program is normally finished, that is until an
     AsynchStopped is generated.

     Provisions of use:
     ForkSucceeded shall be set to an active BooleanVariable object.
     Parameters shall be set to a list of values corresponding to the expected
     parameters of the external procedural code. The order of the Parameters list
     shall correspond to the order of parameters of the procedural code. Parameters
     passed by value shall be set directly to the corresponding value. Parameters
     passed by reference shall be passed via active Variable objects of the
     corresponding data type.
 */
MHEG5ErrorCode MHEG5fork(MHEG5Root *target, MHEG5GList *params)
{
   MHEG5ErrorCode rc;

   assert(target);

   if (!params)
   {
      rc = MHEG5ERR_WRONGNUMBEROFPARAMS;
   }
   else
   {
      /* Check that target class is a subclass of Program */
      switch (target->clazz)
      {
         default:
            /* Target class is not a subclass of Program */
            rc = MHEG5ERR_WRONGTARGET;
            break;

         case MHEG5REMOTEPROGRAM:
         case MHEG5INTERCHANGEDPROGRAM:
            /* Target class is not a supported by UK Profile - or any other ..yet */
            rc = MHEG5ERR_NOTSUPPORTEDBYPROFILE;
            break;

         case MHEG5RESIDENTPROGRAM:
            /* 1. If the Program is non-available, apply the Preparation behaviour. */
            if (!target->availabilityStatus)
            {
               MHEG5programPrepare((MHEG5Program *)target);
            }
            /* 2. If the Program is active, disregard this action. Otherwise, */
            if (target->runningStatus)
            {
               rc = MHEG5ERR_NOERROR;
            }
            else
            {
               /* 3. Apply the Activation behaviour. */
               ((MHEG5Program *) target)->parameter = params;
               ((MHEG5Program *) target)->forked = MHEG5TRUE;

               rc = MHEG5programActivate((MHEG5Program *)target);

               if (rc == MHEG5ERR_NOERROR)
               {
                  if (((MHEG5Program *)target)->forkSucceededValue == NULL)
                  {
                     /* This program was invoked with a Fork action, and has already
                      * finished.
                      * Perform the final steps of the second part of the Fork action:
                      *  3. Apply the Deactivation behaviour.
                      *  4. Generate an AsynchStopped event.
                      */
                     MHEG5programDeactivate((MHEG5Program *)target);
                     MHEG5sendEvent(target, MHEG5ASYNCHSTOPPED, 0);
                  }
               }
            }
            break;
      }
   }
   return rc;
}

/*
     void MHEG5stop(target,params)
     Implemented in Presentable Class!!
 */