ASPEN_GetStoryInfo

Purpose

Retrieve information about a news story.

Call Syntax

#include <aspen.h>

…

AspenRequest(slp->server_session, ASPEN_GetStoryInfo, (void *)&newsNotice->story_handle, &story_output);

…

Parameters

Input

A void pointer to a news story’s handle.

Output

A pointer to an ASPEN_GET_STORY_INFO_OUTPUT structure.

Structures

typedef struct

{

   long story_handle;

}ASPEN_GET_STORY_INFO_INPUT;

typedef struct

{

   long    story_number;

   long    story_time;

   short   story_size;

   USHORT  character_set;

   char    title[ASPEN_MAX_NEWSTITLE_LENGTH];

}ASPEN_GET_STORY_INFO_OUTPUT;

Remarks

To collect news data, a client application requires a storage structure—a multi-dimensional array, a list control, a flex grid control, or some other device capable of holding multiple data elements. Such a structure should not only hold the obvious—headlines and stories—but at a minimum story handles and numbers, for a client application accesses headlines and story text using a story’s handle or its number.

You can also retrieve a story’s text by its number. Call AspenRequest() with the ASPEN_GetNumberedStory service.

A story's handle and number are available in the ASPEN_NEWS_NOTICE structure whenever AspenEvent() receives an ASPEN_NewsNotice.

The principal use of ASPEN_GetStoryInfo is to retrieve a story's headline. A story's title and the intra-day time at which the Server received the story (which typically comprise a headline) are available by calling AspenRequest() with the ASPEN_GetStoryInfo service.

A story’s text is available by calling AspenRequest() with the ASPEN_GetNewsStory.

An application designed to enable users to display stories based on headline content should adhere to the following AspenRequest() call progression:

1. Call ASPEN_SetNewsWatch to enable ASPEN_NewsNotice events, which allows access story handles and numbers.
    

2. Call ASPEN_GetStoryInfo to get a story's title and intra-day time (ASPEN_GetStoryInfo's input structure requires a story handle).
    

3. Call ASPEN_GetNewsStory to get a story's text (ASPEN_GetNewsStory's input structure requires a story handle).
    

In short, 3 requires 2, and 2 requires 1.

A client application that supports news typically displays headlines (2 requires 1), and only asks for news if a user selects a headline that he or she wants to read (3 requires 2).

Return Value

ASPEN_OK

See Also

AspenRequest()

ASPEN_NEWS_NOTICE

ASPEN_MAX_NEWSTITLE_LENGTH

ASPEN_GetNewsStory

ASPEN_GetNumberedStory

ASPEN_SetNewsWatch

ASPEN_GET_NUMBERED_STORY2_OUTPUT

Example

void CSuperQuoteDlg::DoASPEN_EventHandling()

{

   ASPEN_INSTRUMENT_UPDATE_NOTICE      *instrumentUpdate;

   …  

   do{

start:

      WaitForSingleObject(GLOBAL_eventThreadHandle,80);

      retval = AspenEvent(&event, &notice);

      if (retval == ASPEN_OK)

      {

         CWnd *Super = FindWindow(NULL,"SuperQuoter'");

         CWnd *News = FindWindow(NULL,"AspenClient News");

         switch(event)

         {

            case ASPEN_AlertNotice:

            …

            case ASPEN_NewsNotice:

               newsNotice = (ASPEN_NEWS_NOTICE *)notice;

               if(!News)

               {

                  strText.Format("*******  NEWS NOTICE  *******");

                  m_HistoryEdit.AppendString(strText);

               }

               else

               {

                  ASPEN_GET_STORY_INFO_OUTPUT story_output;

                  server_list                 *slp = list;

                  char                        buf[9];

                  int                         retval;

                  retval = AspenRequest(slp->server_session, ASPEN_GetStoryInfo, (void *)&newsNotice->story_handle, &story_output);

                  StoryHandle[i] = newsNotice->story_handle;

                  i++;

                  time_of_day = time(NULL);

                  localTime = gmtime(&time_of_day);

                  AspenTimeToANSITime(story_output.story_time, 0, 31, localTime, NULL);

                  strftime(buf,sizeof(buf),"%H:%M",localTime);

                  strStoryBuf.Format(" %s\t%d\t%s", buf, story_output.story_number, story_output.title);

                  newsdlg.WriteHeadline();

               }

               break;

         }

         AspenFreeMemory(notice);

      }

   }while(retval == ASPEN_OK);

   if (retval == ASPEN_FN_NO_EVENTS)

   {

      WaitForSingleObject(GLOBAL_eventThreadHandle, 500);  // Take a little break

      goto start;

   }

}