home *** CD-ROM | disk | FTP | other *** search
/ CLIX - Fazer Clix Custa Nix / CLIX-CD.cdr / mac / lib / Mac / AppleEvents.xs < prev    next >
Text File  |  1998-04-05  |  31KB  |  1,329 lines
  1. /* $Header: /home/neeri/MacCVS/MacPerl/perl/ext/Mac/AppleEvents/AppleEvents.xs,v 1.2 1997/11/18 00:52:07 neeri Exp $
  2.  *
  3.  *    Copyright (c) 1996 Matthias Neeracher
  4.  *
  5.  *    You may distribute under the terms of the Perl Artistic License,
  6.  *    as specified in the README file.
  7.  *
  8.  * $Log: AppleEvents.xs,v $
  9.  * Revision 1.2  1997/11/18 00:52:07  neeri
  10.  * MacPerl 5.1.5
  11.  *
  12.  * Revision 1.1  1997/04/07 20:49:07  neeri
  13.  * Synchronized with MacPerl 5.1.4a1
  14.  *
  15.  */
  16.  
  17. #define MAC_CONTEXT
  18.  
  19. #include "EXTERN.h"
  20. #include "perl.h"
  21. #include "XSUB.h"
  22. #include <stdarg.h>
  23. #include <Types.h>
  24. #include <Memory.h>
  25. #include <AppleEvents.h>
  26. #include "PerlAEUtils.h"
  27. #include "SubLaunch.h"
  28.  
  29. typedef int     SysRet;
  30. typedef long    SysRetLong;
  31.  
  32. #define AEFail(error)   if (gLastMacOSErr = (error)) { XSRETURN_UNDEF; } else 0
  33.  
  34. MODULE = Mac::AppleEvents   PACKAGE = AEDesc
  35.  
  36. AEDesc
  37. _new(package, type='null', data=0)
  38.     SV *        package
  39.     OSType  type
  40.     Handle  data
  41.     CODE:
  42.     {
  43.         RETVAL.descriptorType   =   type;
  44.         RETVAL.dataHandle           =   data;
  45.     }
  46.     OUTPUT:
  47.     RETVAL
  48.  
  49. OSType
  50. type(desc, newType=0)
  51.     AEDesc  desc
  52.     OSType  newType
  53.     CODE:
  54.     {
  55.         if (items>1)
  56.             desc.descriptorType =   newType;
  57.         RETVAL = desc.descriptorType;
  58.     }
  59.     OUTPUT:
  60.     desc
  61.     RETVAL
  62.  
  63. Handle
  64. data(desc, newData=0)
  65.     AEDesc  desc
  66.     Handle  newData
  67.     CODE:
  68.     {
  69.         if (items>1)
  70.             desc.dataHandle =   newData;
  71.         RETVAL = desc.dataHandle;
  72.     }
  73.     OUTPUT:
  74.     desc
  75.     RETVAL
  76.  
  77. MODULE = Mac::AppleEvents   PACKAGE = AEKeyDesc
  78.  
  79. AEKeyDesc
  80. _new(package, key=0, type='null', data=0)
  81.     SV *        package
  82.     OSType  key
  83.     OSType  type
  84.     Handle  data
  85.     CODE:
  86.     {
  87.         RETVAL.descKey                              =   key;
  88.         RETVAL.descContent.descriptorType   =   type;
  89.         RETVAL.descContent.dataHandle           =   data;
  90.     }
  91.     OUTPUT:
  92.     RETVAL
  93.  
  94. OSType
  95. key(desc, newKey=0)
  96.     AEKeyDesc   desc
  97.     OSType      newKey
  98.     CODE:
  99.     {
  100.         if (items>1)
  101.             desc.descKey    =   newKey;
  102.         RETVAL = desc.descKey;
  103.     }
  104.     OUTPUT:
  105.     desc
  106.     RETVAL
  107.  
  108. OSType
  109. type(desc, newType=0)
  110.     AEKeyDesc   desc
  111.     OSType      newType
  112.     CODE:
  113.     {
  114.         if (items>1)
  115.             desc.descContent.descriptorType =   newType;
  116.         RETVAL = desc.descContent.descriptorType;
  117.     }
  118.     OUTPUT:
  119.     desc
  120.     RETVAL
  121.  
  122. Handle
  123. data(desc, newData=0)
  124.     AEKeyDesc   desc
  125.     Handle      newData
  126.     CODE:
  127.     {
  128.         if (items>1)
  129.             desc.descContent.dataHandle =   newData;
  130.         RETVAL = desc.descContent.dataHandle;
  131.     }
  132.     OUTPUT:
  133.     desc
  134.     RETVAL
  135.  
  136. MODULE = Mac::AppleEvents   PACKAGE = Mac::AppleEvents
  137.  
  138. =head2 Raw AppleEvent Interface
  139.  
  140. =over 4
  141.  
  142. =item AECreateDesc TYPE, DATA
  143.  
  144. The AECreateDesc function creates a new descriptor record that incorporates the
  145. specified data.
  146.  
  147. =cut
  148. AEDesc
  149. AECreateDesc(typeCode, data)
  150.     OSType  typeCode
  151.     SV *        data
  152.     CODE:
  153.     {
  154.         void *  dataPtr;
  155.         STRLEN  dataSize;
  156.         
  157.         dataPtr = SvPV(data, dataSize);
  158.         
  159.         AEFail(AECreateDesc(typeCode, dataPtr, dataSize, &RETVAL));
  160.     }
  161.     OUTPUT:
  162.     RETVAL
  163.  
  164. =item AECoerce TYPE, DATA, NEWTYPE
  165.  
  166. =item AECoerceDesc DESC, NEWTYPE
  167.  
  168. The AECoerceDesc function attempts to create a new descriptor record by coercing
  169. the specified descriptor record. AECoerce attempts the same with a Perl data string.
  170.  
  171. =cut
  172. AEDesc
  173. AECoerce(typeCode, data, toType)
  174.     OSType  typeCode
  175.     SV *        data
  176.     OSType  toType
  177.     CODE:
  178.     {
  179.         void *  dataPtr;
  180.         STRLEN  dataSize;
  181.         
  182.         dataPtr = SvPV(data, dataSize);
  183.         AEFail(AECoercePtr(typeCode, dataPtr, dataSize, toType, &RETVAL));
  184.     }
  185.     OUTPUT:
  186.     RETVAL
  187.  
  188. AEDesc
  189. AECoerceDesc(theAEDesc, toType)
  190.     AEDesc  &theAEDesc
  191.     OSType  toType
  192.     CODE:
  193.     AEFail(AECoerceDesc(&theAEDesc, toType, &RETVAL));
  194.     OUTPUT:
  195.     RETVAL
  196.  
  197. =item AEDisposeDesc DESC
  198.  
  199. Deallocate the memory used by a descriptor record. 
  200.  
  201.     if ( !AEDisposeDesc($desc) ) {
  202.         # error occurred
  203.     }
  204.  
  205. =cut
  206. MacOSRet
  207. AEDisposeDesc(theAEDesc)
  208.     AEDesc  &theAEDesc
  209.  
  210. =item AEDuplicateDesc DESC
  211.  
  212. Creates a new descriptor record by copying the
  213. descriptor record from the parameter $DESC.
  214.  
  215.     $newDesc = AEDuplicateDesc($desc);
  216.     if ( defined $newDesc ) {
  217.         # do something productive
  218.     }
  219.  
  220. =cut
  221. AEDesc
  222. AEDuplicateDesc(theAEDesc)
  223.     AEDesc  &theAEDesc
  224.     CODE:
  225.     AEFail(AEDuplicateDesc(&theAEDesc, &RETVAL));
  226.     OUTPUT:
  227.     RETVAL
  228.  
  229. =item AECreateList FACTOR, BOOL
  230.  
  231. The AECreateList function creates an empty descriptor list (BOOL is 0),
  232. or AE record (BOOL is nonzero). FACTOR contains the common prefix for each
  233. descriptor or is empty.
  234.  
  235.     $list = AECreateList("", 0);
  236.     if ( defined $list ) {
  237.         # do something productive
  238.     }
  239.  
  240. =cut
  241. AEDesc
  242. AECreateList(factoring, isRecord)
  243.     SV *        factoring
  244.     Boolean isRecord
  245.     CODE:
  246.     {
  247.         void *  factoringPtr;
  248.         STRLEN  factoredSize;
  249.         
  250.         factoringPtr    =   SvPV(factoring, factoredSize);
  251.         AEFail(AECreateList(factoringPtr, factoredSize, isRecord, &RETVAL));
  252.     }
  253.     OUTPUT:
  254.     RETVAL
  255.  
  256. =item AECountItems DESCLIST
  257.  
  258. Count the number of descriptor records in any descriptor list. The result
  259. is C<undef> if the list is invalid.
  260.  
  261. =cut
  262. SysRetLong
  263. AECountItems(theAEDescList)
  264.     AEDesc  &theAEDescList
  265.     CODE:
  266.     AEFail(AECountItems(&theAEDescList, &RETVAL));
  267.     OUTPUT:
  268.     RETVAL
  269.  
  270. =item AEPut DESCLIST, INDEX, TYPE, HANDLE
  271.  
  272. =item AEPutDesc DESCLIST, INDEX, DESC
  273.  
  274. Add a descriptor record to any descriptor list. AEPut will manufacture the 
  275. record to add it to the list.
  276. Return zero if an error was detected.
  277.  
  278. =cut
  279. MacOSRet
  280. AEPut(theAEDescList, index, typeCode, data)
  281.     AEDesc  &theAEDescList
  282.     long        index
  283.     OSType  typeCode
  284.     SV *        data
  285.     CODE:
  286.     {
  287.         void *  dataPtr;
  288.         STRLEN  dataSize;
  289.         
  290.         dataPtr     =   SvPV(data, dataSize);
  291.         RETVAL  =   AEPutPtr(&theAEDescList, index, typeCode, dataPtr, dataSize);
  292.     }
  293.     OUTPUT:
  294.     RETVAL
  295.  
  296. MacOSRet
  297. AEPutDesc(theAEDescList, index, theAEDesc)
  298.     AEDesc  &theAEDescList
  299.     long        index
  300.     AEDesc  &theAEDesc
  301.  
  302. =item AEGetNthDesc DESCLIST, INDEX [, TYPE]
  303.  
  304. The AEGetNthDesc function returns a specified descriptor record from a specified
  305. descriptor list. The result is an AEDesc object and the keyword from a keyword
  306. specified list.
  307.  
  308.     ($Desc, $Key) = AEGetNthDesc($DescList, $i);
  309.     if ( defined $Desc ) {
  310.         # do something productive
  311.     }
  312.  
  313. =cut
  314. void
  315. AEGetNthDesc(theAEDescList, index, desiredType=typeWildCard)
  316.     AEDesc  &theAEDescList
  317.     long        index
  318.     OSType  desiredType
  319.     PPCODE:
  320.     {
  321.         OSType  kw;
  322.         AEDesc  desc;
  323.         
  324.         AEFail(AEGetNthDesc(&theAEDescList, index, desiredType, &kw, &desc));
  325.         XS_XPUSH(AEDesc, desc);
  326.         if (GIMME == G_ARRAY && kw != typeWildCard) {
  327.             XS_XPUSH(OSType, kw);
  328.         }
  329.     }
  330.  
  331. =item AEDeleteItem DESCLIST, INDEX
  332.  
  333. Delete a descriptor record from a descriptor list. All subsequent descriptor
  334. records will then move up one place.
  335.  
  336. =cut
  337. MacOSRet
  338. AEDeleteItem(theAEDescList, index)
  339.     AEDesc  &theAEDescList
  340.     long        index
  341.  
  342. =item AEPutParam EVENT, KEY, TYPE, HANDLE
  343.  
  344. =item AEPutParamDesc EVENT, KEY, DESC
  345.  
  346. Add a descriptor record and a keyword to an Apple event as an Apple event
  347. parameter. AEPutParam creates the descriptor record.
  348.  
  349. =cut
  350. MacOSRet
  351. AEPutParam(theAppleEvent, theAEKeyword, typeCode, data)
  352.     AEDesc  &theAppleEvent
  353.     OSType  theAEKeyword
  354.     OSType  typeCode
  355.     SV *        data
  356.     CODE:
  357.     {
  358.         void *  dataPtr;
  359.         STRLEN  dataSize;
  360.         
  361.         dataPtr     =   SvPV(data, dataSize);
  362.         RETVAL  =   AEPutParamPtr(&theAppleEvent, theAEKeyword, typeCode, dataPtr, dataSize);
  363.     }
  364.     OUTPUT:
  365.     RETVAL
  366.  
  367. MacOSRet
  368. AEPutParamDesc(theAppleEvent, theAEKeyword, theAEDesc)
  369.     AEDesc  &theAppleEvent
  370.     OSType  theAEKeyword
  371.     AEDesc  &theAEDesc
  372.  
  373. =item AEGetParamDesc EVENT, KEY [, TYPE]
  374.  
  375. The AEGetParamDesc function returns the descriptor
  376. record for a specified Apple event parameter, which it attempts to coerce to the
  377. descriptor type specified by TYPE (default is no coercion). 
  378.  
  379. =cut
  380. AEDesc
  381. AEGetParamDesc(theAppleEvent, theAEKeyword, desiredType=typeWildCard)
  382.     AEDesc  &theAppleEvent
  383.     OSType  theAEKeyword
  384.     OSType  desiredType
  385.     CODE:
  386.     AEFail(AEGetParamDesc(&theAppleEvent, theAEKeyword, desiredType, &RETVAL));
  387.     OUTPUT:
  388.     RETVAL
  389.  
  390. =item AEDeleteParam EVENT, KEY
  391.  
  392. Delete an Apple event parameter.
  393. Return zero if an error was detected.
  394.  
  395. =cut
  396. MacOSRet
  397. AEDeleteParam(theAppleEvent, theAEKeyword)
  398.     AEDesc  &theAppleEvent
  399.     OSType  theAEKeyword
  400.  
  401. =item AEGetAttributeDesc EVENT, KEY, TYPE
  402.  
  403. The AEGetAttributeDesc function returns the descriptor
  404. record for the Apple event attribute with the specified keyword.
  405.  
  406. =cut
  407. AEDesc
  408. AEGetAttributeDesc(theAppleEvent, theAEKeyword, desiredType=typeWildCard)
  409.     AEDesc  &theAppleEvent
  410.     OSType  theAEKeyword
  411.     OSType  desiredType
  412.     CODE:
  413.     AEFail(AEGetAttributeDesc(&theAppleEvent, theAEKeyword, desiredType, &RETVAL));
  414.     OUTPUT:
  415.     RETVAL
  416.  
  417. =item AEPutAttribute EVENT, KEY, TYPE, HANDLE
  418.  
  419. =item AEPutAttributeDesc EVENT, KEY, DESC
  420.  
  421. The AEPutAttributeDesc function takes a descriptor record and a keyword and adds
  422. them to an Apple event as an attribute.
  423. AEPutAttribute creates the record from TYPE and HANDLE. 
  424. Return zero if an error was detected.
  425.  
  426. =cut
  427. MacOSRet
  428. AEPutAttribute(theAppleEvent, theAEKeyword, typeCode, data)
  429.     AEDesc  &theAppleEvent
  430.     OSType  theAEKeyword
  431.     OSType  typeCode
  432.     SV *        data
  433.     CODE:
  434.     {
  435.         void *  dataPtr;
  436.         STRLEN  dataSize;
  437.         
  438.         dataPtr     =   SvPV(data, dataSize);
  439.         RETVAL  =   AEPutAttributePtr(&theAppleEvent, theAEKeyword, typeCode, dataPtr, dataSize);
  440.     }
  441.     OUTPUT:
  442.     RETVAL
  443.  
  444. MacOSRet
  445. AEPutAttributeDesc(theAppleEvent, theAEKeyword, theAEDesc)
  446.     AEDesc  &theAppleEvent
  447.     OSType  theAEKeyword
  448.     AEDesc  &theAEDesc
  449.  
  450. =item AECreateAppleEvent CLASS, EVENTID, DESC [, RETURNID [, TRANSACTIONID ] ]
  451.  
  452. The AECreateAppleEvent function creates an Apple event and returns it.
  453. TRANSACTIONID defaults to zero.
  454. RETURNID defaults to kAutoGenerateReturnID.
  455.  
  456. =cut
  457. AEDesc
  458. AECreateAppleEvent(theAEEventClass, theAEEventID, target, returnID=kAutoGenerateReturnID, transactionID=0)
  459.     OSType  theAEEventClass
  460.     OSType  theAEEventID
  461.     AEDesc  &target
  462.     short       returnID
  463.     long        transactionID
  464.     CODE:
  465.     if (gPAECreate)
  466.         AEFail(
  467.             CallOSACreateAppleEventProc(gPAECreate,
  468.                 theAEEventClass, theAEEventID, 
  469.                 &target, returnID, transactionID, &RETVAL, 
  470.                 gPAECreateRefCon));
  471.     else
  472.         AEFail(
  473.             AECreateAppleEvent(
  474.                 theAEEventClass, theAEEventID, 
  475.                 &target, returnID, transactionID, &RETVAL));
  476.     OUTPUT:
  477.     RETVAL
  478.  
  479. =item AESend EVENT, SENDMODE [, SENDPRIORITY [, TIMEOUT ] ]
  480.  
  481. Send the Apple Event EVENT. 
  482. TIMEOUT defaults to kAEDefaultTimeout.
  483. SENDPRIORITY defaults to kAENormalPriority.
  484. Returns the reply if SENDMODE was kAEWaitReply.
  485.  
  486. =cut
  487. AEDesc
  488. AESend(theAppleEvent, sendMode, sendPriority=kAENormalPriority, timeout=kAEDefaultTimeout)
  489.     AEDesc  &theAppleEvent
  490.     long        sendMode
  491.     short       sendPriority
  492.     long        timeout
  493.     CODE:
  494.     if (gPAESend) 
  495.         AEFail(
  496.             CallOSASendProc(gPAESend,
  497.                 &theAppleEvent, &RETVAL, 
  498.                 sendMode, sendPriority, timeout, (AEIdleUPP) &uSubLaunchIdle, nil,
  499.                 gPAESendRefCon));
  500.     else
  501.         AEFail(
  502.             AESend(
  503.                 &theAppleEvent, &RETVAL, 
  504.                 sendMode, sendPriority, timeout, (AEIdleUPP) &uSubLaunchIdle, nil));
  505.     OUTPUT:
  506.     RETVAL
  507.  
  508. =item AEResetTimer REPLY
  509.  
  510. The Apple Event Manager for the server
  511. application uses the default reply to send a Reset Timer event to the client
  512. application; the Apple Event Manager for the client application's computer
  513. intercepts this Apple event and resets the client application's timer for the
  514. Apple event.
  515.  
  516. =cut
  517. MacOSRet
  518. AEResetTimer(reply)
  519.     AEDesc  &reply
  520.  
  521. =item AESuspendTheCurrentEvent EVENT
  522.  
  523. After a server application makes a successful call to the
  524. AESuspendTheCurrentEvent function, it is no longer required to return a result or
  525. a reply for the Apple event that was being handled. The result is zero if no error
  526. was detected.
  527.  
  528. =cut
  529. MacOSRet
  530. AESuspendTheCurrentEvent(theAppleEvent)
  531.     AEDesc  &theAppleEvent
  532.  
  533. =item AEResumeTheCurrentEvent EVENT [, FLAGS, REFCON]
  534.  
  535. The Apple Event
  536. Manager resumes handling the specified Apple event using the handler specified in
  537. the FLAGS parameter, if any. If FLAGS and REFCON are missing, 
  538. AEResumeTheCurrentEvent simply informs the Apple Event Manager that
  539. the specified event has been handled.
  540.  
  541. =cut
  542. AEDesc
  543. AEResumeTheCurrentEvent(theAppleEvent, flags=kAENoDispatch, handlerRefcon=0)
  544.     AEDesc  &theAppleEvent
  545.     long     flags
  546.     long     handlerRefcon
  547.     CODE:
  548.     AEFail(
  549.         AEResumeTheCurrentEvent(
  550.             &theAppleEvent, &RETVAL, (AEEventHandlerUPP) flags, handlerRefcon));
  551.     OUTPUT:
  552.     RETVAL
  553.  
  554. =item AEGetTheCurrentEvent
  555.  
  556. Get the Apple event that is currently being handled. 
  557.  
  558. =cut
  559. AEDesc
  560. AEGetTheCurrentEvent()
  561.     CODE:
  562.     AEFail(AEGetTheCurrentEvent(&RETVAL));
  563.     OUTPUT:
  564.     RETVAL
  565.  
  566. =item AESetTheCurrentEvent EVENT
  567.  
  568. There is usually no reason for your application to use the AESetTheCurrentEvent
  569. function.
  570.  
  571. =cut
  572. MacOSRet
  573. AESetTheCurrentEvent(theAppleEvent)
  574.     AEDesc  &theAppleEvent
  575.  
  576. =item AEGetInteractionAllowed
  577.  
  578. The AEGetInteractionAllowed function returns a value
  579. that indicates the user interaction preferences for responding to an Apple event.
  580. The result is C<undef> if an error was detected.
  581.  
  582. =cut
  583. SysRet
  584. AEGetInteractionAllowed()
  585.     CODE:
  586.     {
  587.         char    level;
  588.         
  589.         AEFail(AEGetInteractionAllowed((AEInteractAllowed *)&level));
  590.         RETVAL = level;
  591.     }
  592.     OUTPUT:
  593.     RETVAL
  594.  
  595. =item AESetInteractionAllowed LEVEL
  596.  
  597. The AESetInteractionAllowed function sets the user interaction level for a server
  598. application's response to an Apple event. The result is zero if no error was detected.
  599.  
  600. =cut
  601. MacOSRet
  602. AESetInteractionAllowed(level)
  603.     char    level
  604.     CODE:
  605.     RETVAL = AESetInteractionAllowed((AEInteractAllowed)level);
  606.     OUTPUT:
  607.     RETVAL
  608.  
  609. =item AEInstallEventHandler CLASS, EVENTID, HANDLER, HANDLERREFCON [, SYSTEM]
  610.  
  611. The AEInstallEventHandler function creates an entry in the Apple event dispatch
  612. table. You must supply parameters that specify the event class, the event ID, the
  613. address of the handler that handles Apple events of the specified event class and
  614. event ID, and whether the handler is to be added to the system Apple event
  615. dispatch table or your application's Apple event dispatch table. You can also
  616. specify a reference constant that the Apple Event Manager passes to your handler
  617. whenever your handler processes an Apple event.
  618.  
  619.     if (!AEInstallEventHandler(kCoreEventClass, kAEOpenDocuments, 'OpenDocument', 0) ) {
  620.         # an error occurred.
  621.     }
  622.  
  623. A much more uniform (and Perl-ish) method is available using the hash arrays
  624. %AppleEvent and %SysAppleEvent to bind handlers to event types.
  625.  
  626.     $AppleEvent{kCoreEventClass, kAEOpenDocuments} = 'OpenDocument';
  627.     ...
  628.     delete $AppleEvent{kCoreEventClass, kAEOpenDocuments};
  629.  
  630. =cut
  631. MacOSRet
  632. AEInstallEventHandler(theAEEventClass, theAEEventID, handler, handlerRefcon, isSysHandler=0)
  633.     OSType  theAEEventClass
  634.     OSType  theAEEventID
  635.     SV *        handler
  636.     SV *        handlerRefcon
  637.     Boolean isSysHandler
  638.     CODE:
  639.     {
  640.         RETVAL = PAEInstallEventHandler(theAEEventClass, theAEEventID, handler, handlerRefcon, isSysHandler);
  641.     }
  642.     OUTPUT:
  643.     RETVAL
  644.  
  645. =item AERemoveEventHandler CLASS, EVENTID [, SYSTEM]
  646.  
  647. The AERemoveEventHandler function removes the Apple event dispatch table entry
  648. you specify in the parameters CLASS, EVENTID, and SYSTEM. 
  649.  
  650. =cut
  651. MacOSRet
  652. AERemoveEventHandler(theAEEventClass, theAEEventID, isSysHandler=0)
  653.     OSType  theAEEventClass
  654.     OSType  theAEEventID
  655.     Boolean isSysHandler
  656.     CODE:
  657.     RETVAL = PAERemoveEventHandler(theAEEventClass, theAEEventID, isSysHandler);
  658.     OUTPUT:
  659.     RETVAL
  660.  
  661. =item AEGetEventHandler CLASS, EVENTID [, SYSTEM]
  662.  
  663. The AEGetEventHandler function returns the handler and handlerrefcon for
  664. the specified class and event. 
  665.  
  666.     ($proc, $refcon) = AEGetEventHandler("aevt", "oapp");
  667.  
  668. =cut
  669. void
  670. AEGetEventHandler(theAEEventClass, theAEEventID, isSysHandler=0)
  671.     OSType  theAEEventClass
  672.     OSType  theAEEventID
  673.     Boolean isSysHandler
  674.     PPCODE:
  675.     {
  676.         SV * handler = sv_newmortal();
  677.         SV * refCon  = sv_newmortal();
  678.         
  679.         AEFail(
  680.             PAEGetEventHandler(
  681.                 theAEEventClass, theAEEventID, handler, refCon, isSysHandler));
  682.         XPUSHs(handler);
  683.         if (GIMME == G_ARRAY) {
  684.             XPUSHs(refCon);
  685.         }
  686.     }
  687.  
  688. =item AEManagerInfo KEY
  689.  
  690. Obtain information about the version of the Apple Event Manager currently
  691. available or the number of processes that are currently recording Apple events. 
  692. The result is C<undef> if an error occurred.
  693.  
  694. =back
  695.  
  696. =cut
  697. SysRetLong
  698. AEManagerInfo(keyWord)
  699.     OSType  keyWord
  700.     CODE:
  701.     AEFail(AEManagerInfo(keyWord, &RETVAL));
  702.     OUTPUT:
  703.     RETVAL
  704.  
  705.  
  706. =head2 AEGizmos Build/Print
  707.  
  708. The Apple Event Gizmos were developed by Jens Peter Alfke at Apple as a vastly
  709. speeded up AE library. Consult the AEGizmo documentation for details of usage
  710. of the library. The Build/Print facility uses a formatting convention similar
  711. to scanf/printf to put things together.
  712.  
  713. =item AEBuild FORMAT, PARM, ...
  714.  
  715. Build an AppleEvent descriptor using the format per the Gizmo documentation
  716. and return it.
  717.  
  718. =cut
  719. AEDesc
  720. AEBuild(format, ...)
  721.     char *  format
  722.     CODE:
  723.     {
  724.         int item = 1;
  725.         char *formscan = format;
  726.         
  727.         PAEClearArgs();
  728.         for (;item<items;++item) 
  729.             if (!PAEDoNextParam(&formscan, ST(item)))
  730.                 croak("Too many arguments to AEBuild()");
  731.             
  732.         if (PAENextParam(&formscan))
  733.             croak("Not enough arguments to AEBuild()");
  734.         AEFail(vAEBuild(&RETVAL, format, gPAEArgs));
  735.     }
  736.     OUTPUT:
  737.     RETVAL
  738.  
  739. =item AEBuildParameters EVENT, FORMAT, PARM, ...
  740.  
  741. Build parameters for an existing AppleEvent EVENT.
  742.  
  743.     if (!AEBuildParameters($reply, $format, $parm1, $parm2) ) {
  744.         # an error occurred
  745.     }
  746.  
  747. =cut
  748. MacOSRet
  749. AEBuildParameters(event, format, ...)
  750.     AEDesc  &event
  751.     char *  format
  752.     CODE:
  753.     {
  754.         int item = 2;
  755.         char *formscan = format;
  756.         
  757.         PAEClearArgs();
  758.         for (;item<items;++item) 
  759.             if (!PAEDoNextParam(&formscan, ST(item)))
  760.                 croak("Too many arguments to AEBuildParameters()");
  761.             
  762.         if (PAENextParam(&formscan))
  763.             croak("Not enough arguments to AEBuildParameters()");
  764.         RETVAL = vAEBuildParameters(&event, format, gPAEArgs);
  765.     }
  766.     OUTPUT:
  767.     RETVAL
  768.  
  769. =item AEBuildAppleEvent CLASS, ID, ADDRESSTYPE, ADDRESS, RETURNID, TRANSACTIONID, FORMAT, PARMS, ...
  770.  
  771. Construct an AppleEvent from the format and parameters and return it.
  772.  
  773. =cut
  774. AEDesc
  775. AEBuildAppleEvent(theClass, theID, addressType, address, returnID, transactionID, paramsFmt, ... )
  776.     OSType  theClass
  777.     OSType  theID
  778.     OSType  addressType
  779.     SV *        address
  780.     short       returnID
  781.     long        transactionID
  782.     char *  paramsFmt
  783.     CODE:
  784.     {
  785.         int     item = 7;
  786.         char *  formscan = paramsFmt;
  787.         char *  addressPtr;
  788.         STRLEN  addressLen;
  789.         AEDesc  targetDesc;
  790.         
  791.         PAEClearArgs();
  792.         addressPtr = SvPV(address, addressLen);
  793.         for (;item<items;++item) 
  794.             if (!PAEDoNextParam(&formscan, ST(item)))
  795.                 croak("Too many arguments to AEBuildAppleEvent()");
  796.             
  797.         if (PAENextParam(&formscan))
  798.             croak("Not enough arguments to AEBuildAppleEvent()");
  799.         AEFail(AECreateDesc(addressType, addressPtr, addressLen, &targetDesc));
  800.         if (gPAECreate)
  801.             AEFail(
  802.                 CallOSACreateAppleEventProc(gPAECreate,
  803.                     theClass, theID, 
  804.                     &targetDesc, returnID, transactionID, &RETVAL, 
  805.                     gPAECreateRefCon));
  806.         else
  807.             AEFail(
  808.                 AECreateAppleEvent(
  809.                     theClass, theID, 
  810.                     &targetDesc, returnID, transactionID, &RETVAL));
  811.         AEDisposeDesc(&targetDesc);
  812.         AEFail(vAEBuildParameters(&RETVAL, paramsFmt, gPAEArgs));
  813.     }
  814.     OUTPUT:
  815.     RETVAL
  816.  
  817. =item AEPrint DESC
  818.  
  819. Return a string version of the descriptor record. The result is C<undef>
  820. if an error occurred.
  821.  
  822. =cut
  823. SV *
  824. AEPrint(desc)
  825.     AEDesc  &desc
  826.     CODE:
  827.     {
  828.         long    length;
  829.         
  830.         AEFail(AEPrintSize(&desc, &length));
  831.         RETVAL = newSVpv("", length);
  832.         AEPrint(&desc, SvPVX(RETVAL), length);
  833.         SvCUR(RETVAL) = length-1;
  834.     }
  835.     OUTPUT:
  836.     RETVAL
  837.  
  838. =head2 AEGizmos Subdescriptors
  839.  
  840. The Apple Event Gizmos subdescriptor approach uses a dictionary method for
  841. extracting and constructing descriptors.  Parsing an Apple Event using the
  842. dictionary is very time efficient, and translating to and from the dictionary
  843. tables is quick and efficient.
  844.  
  845. =item AEDescToSubDesc DESC
  846.  
  847. Translate DESC to a subdescriptor (dictionary entry). 
  848. Return the subdescriptor.
  849.  
  850. =cut
  851. AESubDesc
  852. AEDescToSubDesc(desc)
  853.     AEDesc  &desc
  854.     CODE:
  855.     AEDescToSubDesc(&desc, &RETVAL);
  856.     OUTPUT:
  857.     RETVAL
  858.  
  859. =item AEGetSubDescType SUBDESC
  860.  
  861. Return the type of the subdescriptor.
  862.  
  863. =cut
  864. OSType
  865. AEGetSubDescType(subdesc)
  866.     AESubDesc   &subdesc
  867.  
  868. =item AEGetSubDescBasicType SUBDESC
  869.  
  870. Return the basic type of the subdescriptor. Differs from AEGetSubDescType
  871. in handling of coerced records.
  872.  
  873. =cut
  874. OSType
  875. AEGetSubDescBasicType(subdesc)
  876.     AESubDesc   &subdesc
  877.  
  878. =item AESubDescIsListOrRecord SUBDESC
  879.  
  880. Return nonzero if the subdescriptor is a list or record.
  881.  
  882. =cut
  883. Boolean
  884. AESubDescIsListOrRecord(subdesc)
  885.     AESubDesc   &subdesc
  886.  
  887. =item AEGetSubDescData SUBDESC
  888.  
  889. Returns the data of the subdescriptor. 
  890.  
  891. =cut
  892. SV *
  893. AEGetSubDescData(subdesc)
  894.     AESubDesc   &subdesc
  895.     CODE:
  896.     {
  897.         void *data;
  898.         long    length;
  899.         
  900.         data        = AEGetSubDescData(&subdesc, &length);
  901.         RETVAL  = newSVpv(data, length);
  902.     }
  903.     OUTPUT:
  904.     RETVAL
  905.  
  906. =item AESubDescToDesc SUBDESC, DESIREDTYPE
  907.  
  908. Translate the subdescriptor back to a descriptor of the desired type.
  909.  
  910. =cut
  911. AEDesc
  912. AESubDescToDesc(subdesc, desiredType=typeWildCard)
  913.     AESubDesc   &subdesc
  914.     OSType      desiredType
  915.     CODE:
  916.     AEFail(AESubDescToDesc(&subdesc, desiredType, &RETVAL));
  917.     OUTPUT:
  918.     RETVAL
  919.  
  920. =item AECountSubDescItems SUBDESC
  921.  
  922. Counts the number of subdescriptor items.
  923.  
  924. =cut
  925. long
  926. AECountSubDescItems(subdesc)
  927.     AESubDesc   &subdesc
  928.     CODE:
  929.     {
  930.         RETVAL = AECountSubDescItems(&subdesc);
  931.         if (RETVAL < 0)
  932.             AEFail((OSErr) RETVAL);
  933.     }
  934.     OUTPUT:
  935.     RETVAL  
  936.  
  937. =item AEGetNthSubDesc SUBDESC,INDEX
  938.  
  939. Returns the item INDEX of the subdescriptor and its type if the subdescriptor
  940. represented a record and not a list.
  941.  
  942. =cut
  943. void
  944. AEGetNthSubDesc(subdesc,index)
  945.     AESubDesc   &subdesc
  946.     long            index
  947.     PPCODE:
  948.     {
  949.         OSType      kw;
  950.         AESubDesc   sub;
  951.         
  952.         AEFail(AEGetNthSubDesc(&subdesc, index, &kw, &sub));
  953.         XS_XPUSH(AESubDesc, sub);
  954.         if (GIMME == G_ARRAY && kw != typeWildCard) {
  955.             XS_XPUSH(OSType, kw);
  956.         }
  957.     }
  958.  
  959. =item AEGetKeySubDesc SUBDESC,KW
  960.  
  961. Returns the keyword indexed item from the subdescriptor.
  962.  
  963. =back
  964.  
  965. =cut
  966. AESubDesc
  967. AEGetKeySubDesc(subdesc,kw)
  968.     AESubDesc   &subdesc
  969.     OSType      kw
  970.     CODE:
  971.     AEFail(AEGetKeySubDesc(&subdesc, kw, &RETVAL));
  972.     OUTPUT:
  973.     RETVAL
  974.  
  975. MODULE = Mac::AppleEvents   PACKAGE = AEStream 
  976.  
  977. =head2 AEStream
  978.  
  979. The Apple Event Gizmos streams approach uses a streaming model for building 
  980. a sequence of descriptors.
  981.  
  982. =item new AEStream
  983.  
  984. =item AEStream::Open 
  985.  
  986. Return a new AEStream.
  987.  
  988. =cut
  989. AEStream
  990. Open()
  991.     CODE:
  992.     AEFail(AEStream_Open(&RETVAL));
  993.     OUTPUT:
  994.     RETVAL
  995.  
  996. =item new AEStream(CLASS, ID, ADDRESSTYPE, ADDRESS [, RETURNID [, TRANSACTIONID ] ])
  997.  
  998. =item AEStream::CreateEvent CLASS, ID, ADDRESSTYPE, ADDRESS, RETURNID, TRANSACTIONID
  999.  
  1000. Create an AEStream attached to a new AppleEvent.
  1001.  
  1002. =cut
  1003. AEStream
  1004. CreateEvent(theClass, theID, addressType, address, returnID=kAutoGenerateReturnID, transactionID=0)
  1005.     OSType  theClass
  1006.     OSType  theID
  1007.     OSType  addressType
  1008.     SV *        address
  1009.     short       returnID
  1010.     long        transactionID
  1011.     CODE:
  1012.     {
  1013.         char *      addressPtr;
  1014.         STRLEN      addressLen;
  1015.         AEDesc      targetDesc;
  1016.         AppleEvent  event;
  1017.         
  1018.         addressPtr = SvPV(address, addressLen);
  1019.         AEFail(AECreateDesc(addressType, addressPtr, addressLen, &targetDesc));
  1020.         if (gPAECreate)
  1021.             AEFail(
  1022.                 CallOSACreateAppleEventProc(gPAECreate,
  1023.                     theClass, theID, 
  1024.                     &targetDesc, returnID, transactionID, &event, 
  1025.                     gPAECreateRefCon));
  1026.         else
  1027.             AEFail(
  1028.                 AECreateAppleEvent(
  1029.                     theClass, theID, 
  1030.                     &targetDesc, returnID, transactionID, &event));
  1031.         AEDisposeDesc(&targetDesc);
  1032.         AEFail(AEStream_OpenEvent(&RETVAL, &event));
  1033.     }
  1034.     OUTPUT:
  1035.     RETVAL
  1036.  
  1037. =item new AEStream(EVENT)
  1038.  
  1039. =item AEStream::OpenEvent EVENT
  1040.  
  1041. Opens the stream on the $EVENT.
  1042. Return C<undef> if an error was detected.
  1043.  
  1044. =cut
  1045. AEStream
  1046. OpenEvent(theEvent)
  1047.     AEDesc  &theEvent
  1048.     CODE:
  1049.     AEFail(AEStream_OpenEvent(&RETVAL, &theEvent));
  1050.     OUTPUT:
  1051.     RETVAL
  1052.  
  1053. =item Close
  1054.  
  1055. Return the descriptor corresponding to the stream, and close it out.
  1056.  
  1057.     $stream->Close;
  1058.  
  1059. =cut
  1060. AEDesc
  1061. Close(stream)
  1062.     AEStream        &stream
  1063.     CODE:
  1064.     AEFail(AEStream_Close(&stream, &RETVAL));
  1065.     OUTPUT:
  1066.     stream
  1067.     RETVAL
  1068.  
  1069. =item Abort STREAM
  1070.  
  1071. Abort the streaming process, and close it out.
  1072.  
  1073.     $stream->Abort;
  1074.  
  1075. =cut
  1076. MacOSRet
  1077. Abort(stream)
  1078.     AEStream        &stream
  1079.     CODE:
  1080.     RETVAL = AEStream_Close(&stream, nil);
  1081.     OUTPUT:
  1082.     stream
  1083.     RETVAL
  1084.  
  1085. =item OpenDesc TYPE
  1086.  
  1087. Start building a descriptor of the given type.
  1088. Return zero if an error was detected.
  1089.  
  1090.     if ( $stream->OpenDesc($type) ) {
  1091.         # Long messy calculation that demonstrates the usefullness of this code
  1092.         if ( $stream->WriteData($calculatedData) 
  1093.          &&  $stream->CloseDesc()
  1094.         ){
  1095.             # then, my work here is done
  1096.         }
  1097.     }
  1098.  
  1099. =cut
  1100. MacOSRet
  1101. OpenDesc(stream, type)
  1102.     AEStream    &stream
  1103.     OSType  type
  1104.     CODE:
  1105.     RETVAL = AEStream_OpenDesc(&stream, type);
  1106.     OUTPUT:
  1107.     stream
  1108.  
  1109. =item WriteData DATA
  1110.  
  1111. Add data to the descriptor.
  1112.  
  1113. =cut
  1114. MacOSRet
  1115. WriteData(stream, data)
  1116.     AEStream    &stream
  1117.     SV *        data
  1118.     CODE:
  1119.     {
  1120.         void *  ptr;
  1121.         STRLEN  length;
  1122.         
  1123.         ptr = SvPV(data, length);
  1124.         RETVAL = AEStream_WriteData(&stream, ptr, length);
  1125.     }
  1126.     OUTPUT:
  1127.     stream
  1128.     RETVAL
  1129.  
  1130. =item CloseDesc
  1131.  
  1132. Finish up the descriptor.
  1133.  
  1134. =cut
  1135. MacOSRet
  1136. CloseDesc(stream)
  1137.     AEStream    &stream
  1138.     CODE:
  1139.     RETVAL = AEStream_CloseDesc(&stream);
  1140.     OUTPUT:
  1141.     stream
  1142.  
  1143. =item WriteDesc TYPE, DATA
  1144.  
  1145. Add the arbitrary data with the given type as a descriptor to the stream.
  1146.  
  1147. =cut
  1148. MacOSRet
  1149. WriteDesc(stream, type, data)
  1150.     AEStream    &stream
  1151.     OSType  type
  1152.     SV *        data
  1153.     CODE:
  1154.     {
  1155.         void *  ptr;
  1156.         STRLEN  length;
  1157.         
  1158.         ptr = SvPV(data, length);
  1159.         RETVAL = AEStream_WriteDesc(&stream, type, ptr, length);
  1160.     }
  1161.     OUTPUT:
  1162.     stream
  1163.     RETVAL
  1164.  
  1165. =item WriteAEDesc STREAM, AEDESC
  1166.  
  1167. Add an Apple Event descriptor to the stream.
  1168.  
  1169. =cut
  1170. MacOSRet
  1171. WriteAEDesc(stream, desc)
  1172.     AEStream    &stream
  1173.     AEDesc  &desc
  1174.     CODE:
  1175.     RETVAL = AEStream_WriteAEDesc(&stream, &desc);
  1176.     OUTPUT:
  1177.     stream
  1178.  
  1179. =item OpenList
  1180.  
  1181. Start building a list of AppleEvent descriptors in the stream.
  1182.  
  1183. =cut
  1184. MacOSRet
  1185. OpenList(stream)
  1186.     AEStream    &stream
  1187.     CODE:
  1188.     RETVAL = AEStream_OpenList(&stream);
  1189.     OUTPUT:
  1190.     stream
  1191.  
  1192. =item CloseList STREAM
  1193.  
  1194. Return zero if an error was detected.
  1195.  
  1196.     if ( $stream->OpenList() ) {
  1197.         for $desc (@descList) {
  1198.             croak unless $stream->WriteAEDesc($desc);
  1199.         }
  1200.         die unless $stream->CloseList();
  1201.     }
  1202.  
  1203. =cut
  1204. MacOSRet
  1205. CloseList(stream)
  1206.     AEStream    &stream
  1207.     CODE:
  1208.     RETVAL = AEStream_CloseList(&stream);
  1209.     OUTPUT:
  1210.     stream
  1211.  
  1212. =item OpenRecord [TYPE]
  1213.  
  1214. Start the process of building a record, to be coerced to the given type.
  1215. =cut
  1216. MacOSRet
  1217. OpenRecord(stream, type=typeAERecord)
  1218.     AEStream    &stream
  1219.     OSType  type
  1220.     CODE:
  1221.     RETVAL = AEStream_OpenRecord(&stream, type);
  1222.     OUTPUT:
  1223.     stream
  1224.  
  1225. =item SetRecordType TYPE
  1226.  
  1227. Change the record type.
  1228.  
  1229. =cut
  1230. MacOSRet
  1231. SetRecordType(stream, type)
  1232.     AEStream    &stream
  1233.     OSType  type
  1234.     CODE:
  1235.     RETVAL = AEStream_SetRecordType(&stream, type);
  1236.     OUTPUT:
  1237.     stream
  1238.  
  1239. =item CloseRecord STREAM
  1240.  
  1241. Close the record currently under construction.
  1242.  
  1243.     if ( $stream->OpenRecord(typeAErecord) ) {
  1244.         for $kdesc (@descList) {
  1245.             die unless $stream->WriteKey($kdesc->key) and 
  1246.                     $stream->WriteAEDesc($kdesc->desc);
  1247.         }
  1248.         die unless $stream->CloseRecord();
  1249.     }
  1250.  
  1251. =cut
  1252. MacOSRet
  1253. CloseRecord(stream)
  1254.     AEStream    &stream
  1255.     CODE:
  1256.     RETVAL = AEStream_CloseRecord(&stream);
  1257.     OUTPUT:
  1258.     stream
  1259.  
  1260. =item WriteKeyDesc KEY, TYPE, DATA
  1261.  
  1262. Add the keyword descriptor to the stream.
  1263.  
  1264. =cut
  1265. MacOSRet
  1266. WriteKeyDesc(stream, key, type, data)
  1267.     AEStream    &stream
  1268.     OSType  key
  1269.     OSType  type
  1270.     SV *        data
  1271.     CODE:
  1272.     {
  1273.         void *  ptr;
  1274.         STRLEN  length;
  1275.         
  1276.         ptr = SvPV(data, length);
  1277.         RETVAL = AEStream_WriteKeyDesc(&stream, key, type, ptr, length);
  1278.     }
  1279.     OUTPUT:
  1280.     stream
  1281.     RETVAL
  1282.  
  1283. =item OpenKeyDesc KEY, TYPE
  1284.  
  1285. Open a descriptor with the given type and key.
  1286. Use CloseDesc() to close it.
  1287.  
  1288. =cut
  1289. MacOSRet
  1290. OpenKeyDesc(stream, key, type)
  1291.     AEStream    &stream
  1292.     OSType  key
  1293.     OSType  type
  1294.     CODE:
  1295.     RETVAL = AEStream_OpenKeyDesc(&stream, key, type);
  1296.     OUTPUT:
  1297.     stream
  1298.  
  1299. =item WriteKey  KEY
  1300.  
  1301. Add the keyword to the immediately following descriptor.
  1302. Return zero if an error was detected.
  1303.  
  1304. =cut
  1305. MacOSRet
  1306. WriteKey(stream, key)
  1307.     AEStream    &stream
  1308.     OSType  key
  1309.     CODE:
  1310.     RETVAL = AEStream_WriteKey(&stream, key);
  1311.     OUTPUT:
  1312.     stream
  1313.  
  1314. =item OptionalParam KEY
  1315.  
  1316. Adds the keyword to the list of optional attributes.
  1317.  
  1318. =back
  1319.  
  1320. =cut
  1321. MacOSRet
  1322. OptionalParam(stream, key)
  1323.     AEStream    &stream
  1324.     OSType  key
  1325.     CODE:
  1326.     RETVAL = AEStream_OptionalParam(&stream, key);
  1327.     OUTPUT:
  1328.     stream
  1329.